rundoc 4.1.4 → 6.0.0

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)
@@ -62,6 +97,43 @@ module Rundoc
     yield self
   end
 
+  def ensure_later_blocks
+    @ensure_later_blocks ||= []
+  end
+
+  def add_ensure_later(dir:, code:, binding:)
+    ensure_later_blocks << {dir: dir, code: code, binding: binding}
+  end
+
+  def run_ensure_later(io:)
+    errors = []
+    ensure_later_blocks.each do |block|
+      io.puts "Running ensure_later block in #{block[:dir]}:\n#{block[:code]}"
+      Dir.chdir(block[:dir]) do
+        capture_stdout_stderr(io) do
+          eval(block[:code], block[:binding]) # rubocop:disable Security/Eval
+        end
+      end
+    rescue => e
+      io.puts "ensure_later block failed in #{block[:dir]}: #{e.message}"
+      io.puts e.backtrace.join("\n")
+      errors << e
+    end
+    ensure_later_blocks.clear
+    errors
+  end
+
+  def capture_stdout_stderr(io)
+    old_stdout = $stdout
+    old_stderr = $stderr
+    $stdout = io
+    $stderr = io
+    yield
+  ensure
+    $stdout = old_stdout
+    $stderr = old_stderr
+  end
+
   def filter_sensitive(sensitive)
     raise "Expecting #{sensitive} to be a hash" unless sensitive.is_a?(Hash)
     @sensitive ||= {}

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"
@@ -24,6 +26,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "aws-sdk-s3", "~> 1"
   gem.add_dependency "dotenv"
+  gem.add_dependency "cgi", ">= 0.3.6"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "mocha"

data/test/integration/ensure_later_test.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class IntegrationEnsureLaterTest < Minitest::Test
+  def test_runs_on_success
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "yes")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert marker.exist?, "ensure_later block should have run on success"
+        assert_equal "yes", marker.read
+      end
+    end
+  end
+
+  def test_runs_on_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "cleaned")
+          ```
+
+          ```
+          :::>> $ exit 1
+          ```
+        EOF
+
+        assert_raises do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME),
+            on_failure_dir: dir.join(FAILURE_DIRNAME)
+          ).call
+        end
+
+        assert marker.exist?, "ensure_later block should have run on failure"
+        assert_equal "cleaned", marker.read
+      end
+    end
+  end
+
+  def test_multiple_blocks_run_in_order
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("order.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "first")
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", File.read("#{marker}") + ",second")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert_equal "first,second", marker.read
+      end
+    end
+  end
+
+  def test_one_failure_does_not_stop_others
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("second_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          raise "intentional failure"
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "yes")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        error = assert_raises(RuntimeError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+        assert_match(/intentional failure/, error.message)
+
+        assert marker.exist?, "second ensure_later should still run after first fails"
+      end
+    end
+  end
+
+  def test_success_plus_ensure_failure_is_overall_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          raise "cleanup failed"
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        error = assert_raises(RuntimeError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+
+        assert_match(/cleanup failed/, error.message)
+      end
+    end
+  end
+
+  def test_dir_rundoc_root
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("root_marker.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir subdir
+          :::>> $ cd subdir
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :rundoc_root)
+          File.write("#{marker}", Dir.pwd)
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        cli = Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        )
+        output_dir = cli.execution_context.output_dir.realpath.to_s
+
+        cli.call
+
+        assert marker.exist?, "ensure_later with dir: :rundoc_root should run"
+        assert_equal output_dir, marker.read
+      end
+    end
+  end
+
+  def test_output_not_in_document
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          puts "THIS SHOULD NOT APPEAR"
+          ```
+
+          ```
+          :::>> $ echo "visible"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        readme = dir.join(SUCCESS_DIRNAME).join("README.md").read
+        refute_match(/THIS SHOULD NOT APPEAR/, readme)
+        assert_match(/visible/, readme)
+      end
+    end
+  end
+
+  def test_invalid_dir_raises
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :invalid)
+          puts "should not run"
+          ```
+        EOF
+
+        assert_raises(ArgumentError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+      end
+    end
+  end
+
+  def test_shared_binding_with_rundoc
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("binding_test.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc
+          def my_helper
+            "from_rundoc"
+          end
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", my_helper)
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert_equal "from_rundoc", marker.read
+      end
+    end
+  end
+
+  def test_runs_on_failure_from_subdirectory
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir myapp
+          :::>> $ cd myapp
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "cleaned")
+          ```
+
+          ```
+          :::>> $ exit 1
+          ```
+        EOF
+
+        assert_raises do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME),
+            on_failure_dir: dir.join(FAILURE_DIRNAME)
+          ).call
+        end
+
+        assert marker.exist?, "ensure_later from subdirectory should run even on failure"
+        assert_equal "cleaned", marker.read
+      end
+    end
+  end
+end

data/test/integration/print_test.rb

@@ -50,6 +50,57 @@ class IntegrationPrintTest < Minitest::Test
     end
   end
 
+  def test_rundoc_configure_defines_variable_accessible_from_erb
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-- rundoc.configure
+      @shared_value = "#{key}"
+      ```
+
+      ```
+      :::-> print.erb
+      <%= @shared_value %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
+        assert_includes actual, key
+      end
+    end
+  end
+
+  def test_erb_defines_variable_accessible_from_rundoc_configure
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-> print.erb
+      <% @from_erb = "#{key}" %>
+      ```
+
+      ```
+      :::-- rundoc.configure
+      @roundtripped = @from_erb + "_via_configure"
+      ```
+
+      ```
+      :::-> print.erb
+      <%= @roundtripped %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
+        assert_includes actual, "#{key}_via_configure"
+      end
+    end
+  end
+
   def test_erb_in_block
     contents = <<~RUBY
       ```

data/test/rundoc/code_commands/append_file_test.rb

@@ -7,8 +7,13 @@ class AppendFileTest < Minitest::Test
         file = "foo.rb"
         `echo 'foo' >> #{file}`
 
-        cc = Rundoc::CodeCommand::FileCommand::Append.new(file)
-        cc << "bar"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new(file),
+          contents: "bar"
+        )
         cc.call
 
         result = File.read(file)
@@ -16,8 +21,13 @@ class AppendFileTest < Minitest::Test
         assert_match(/foo/, result)
         assert_match(/bar/, result)
 
-        cc = Rundoc::CodeCommand::FileCommand::Append.new(file)
-        cc << "baz"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new(file),
+          contents: "baz"
+        )
         cc.call
 
         actual = File.read(file)
@@ -39,8 +49,13 @@ class AppendFileTest < Minitest::Test
         line = 2
         `echo '#{contents}' >> #{file}`
 
-        cc = Rundoc::CodeCommand::FileCommand::Append.new("#{file}##{line}")
-        cc << "gem 'pg'"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new("#{file}##{line}"),
+          contents: "gem 'pg'"
+        )
         cc.call
 
         expected = "source https://rubygems.org\ngem 'pg'\ngem rails, 4.0.0\n\n"
@@ -54,8 +69,13 @@ class AppendFileTest < Minitest::Test
       Dir.chdir(dir) do
         filename = "file-#{Time.now.utc.strftime("%Y%m%d%H%M%S")}.txt"
         FileUtils.touch(filename)
-        cc = Rundoc::CodeCommand::FileCommand::Append.new("file-*.txt")
-        cc << "some text"
+        cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+          render_command: false,
+          render_result: false,
+          io: StringIO.new,
+          user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new("file-*.txt"),
+          contents: "some text"
+        )
         cc.call
 
         assert_equal "\nsome text\n", File.read(filename)
@@ -69,8 +89,13 @@ class AppendFileTest < Minitest::Test
         FileUtils.touch("file-1234.txt")
         FileUtils.touch("file-5678.txt")
         assert_raises do
-          cc = Rundoc::CodeCommand::FileCommand::Append.new("file-*.txt")
-          cc << "some text"
+          cc = Rundoc::CodeCommand::FileCommand::AppendRunner.new(
+            render_command: false,
+            render_result: false,
+            io: StringIO.new,
+            user_args: Rundoc::CodeCommand::FileCommand::AppendArgs.new("file-*.txt"),
+            contents: "some text"
+          )
           cc.call
         end
       end