Merge branch 'main' into schneems/fix-save-on-error

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 - Fix: Include all code sections in the event of a failure, not just the last one (https://github.com/zombocom/rundoc/pull/71)
 
+## 3.1.0
+
+- Add: `--with-contents` flag that accepts a directory. The **contents** of the directory (and not the directory itself) will be copied into the working dir before execution. This is useful for debugging a single rundoc step. ()
+
+For example if `RUNDOC.md` features many smaller docs:
+
+```
+:::>> rundoc.require "./intro.md"
+:::>> rundoc.require "../shared/install_cli.md"
+:::>> rundoc.require "./clone_app.md"
+```
+
+If the command fails on `clone_app.md` then you can rapidly iterate by calling `$ rundoc ./clone_app.md --with-contents failed/my-app` but be careful to not use the same failure directory etc or it will be replaced.
+
 ## 3.0.2
 
 - Fix: Partial output of the document is now written to disk in a `RUNDOC_FAILED.md` file (https://github.com/zombocom/rundoc/pull/69)

lib/rundoc/cli.rb

@@ -24,6 +24,7 @@ def initialize(
       on_success_dir: nil,
       on_failure_dir: nil,
       output_filename: nil,
+      with_contents_dir: nil,
       screenshots_dirname: nil
     )
       @io = io
@@ -37,6 +38,7 @@ def initialize(
       @execution_context = Rundoc::Context::Execution.new(
         output_dir: Dir.mktmpdir,
         source_path: source_path,
+        with_contents_dir: with_contents_dir,
         screenshots_dirname: screenshots_dirname
       )
 
@@ -136,13 +138,23 @@ def call
 
       source_contents = execution_context.source_path.read
       if on_failure_dir.exist? && !Dir.empty?(on_failure_dir)
-        io.puts "## earing on failure directory #{on_failure_dir}"
+        io.puts "## erring on failure directory #{on_failure_dir}"
         clean_dir(
           dir: on_failure_dir,
           description: "on failure directory"
         )
       end
 
+      if execution_context.with_contents_dir
+        io.puts "## Copying contents from #{execution_context.with_contents_dir} to tmp working dir"
+        Dir.chdir(execution_context.with_contents_dir) do
+          FileUtils.cp_r(
+            ".",
+            execution_context.output_dir
+          )
+        end
+      end
+
       io.puts "## Working dir is #{execution_context.output_dir}"
       Dir.chdir(execution_context.output_dir) do
         parser = Rundoc::Parser.new(

lib/rundoc/cli_argument_parser.rb

@@ -8,7 +8,8 @@ module Rundoc
   #
   # Example:
   #
-  #   cli = CLIArgumentParser.new(argv: ARGV).to_cli
+  #   options = Rundoc::CLIArgumentParser.new(argv: ARGV).call.options
+  #   cli = Rundoc::CLI.new(**options)
   #   cli.call
   #
   class CLIArgumentParser
@@ -109,6 +110,10 @@ def call
           @exit_obj.exit(0)
         end
 
+        opts.on("--with-contents <dir>", "Copies contents of directory into the tmp working dir") do |v|
+          options[:with_contents_dir] = v
+        end
+
         opts.on("--on-success-dir <dir>", "Success dir, relative to CWD. i.e. `<rundoc.md/dir>/#{CLI::DEFAULTS::ON_SUCCESS_DIR}/`.") do |v|
           options[:on_success_dir] = v
         end

lib/rundoc/code_command/background/process_spawn.rb

@@ -43,7 +43,7 @@ def self.find(name)
       @tasks[name]
     end
 
-    attr_reader :log, :pid
+    attr_reader :log, :pid, :command
 
     def initialize(command, timeout: 5, log: Tempfile.new("log"), out: "2>&1")
       @command = command
@@ -68,7 +68,7 @@ def wait(wait_value = nil, timeout_value = @timeout_value)
         end
       end
     rescue Timeout::Error
-      raise "Timeout waiting for #{@command.inspect} to find a match using #{wait_value.inspect} in \n'#{log.read}'"
+      raise "Timeout (#{timeout_value}s) waiting for #{@command.inspect} to find a match using #{wait_value.inspect} in \n'#{log.read}'"
     end
 
     def alive?

lib/rundoc/code_command/background/start.rb

@@ -15,6 +15,7 @@ def initialize(command, name:, wait: nil, timeout: 5, log: Tempfile.new("log"),
         log: log,
         out: out
       )
+      puts "Spawning commmand: `#{@spawn.command}`"
       ProcessSpawn.add(@name, @spawn)
     end
 

lib/rundoc/context/execution.rb

@@ -9,13 +9,16 @@ class Execution
         # The directory we are actively manipulating
         :output_dir,
         # Directory to store screenshots, relative to output_dir
-        :screenshots_dir
+        :screenshots_dir,
+        # Directory we are copying from, i.e. a directory to source from could be nil
+        :with_contents_dir
 
-      def initialize(source_path:, output_dir:, screenshots_dirname:)
+      def initialize(source_path:, output_dir:, screenshots_dirname:, with_contents_dir:)
         @source_path = Pathname(source_path).expand_path
         @source_dir = @source_path.parent
         @output_dir = Pathname(output_dir).expand_path
         @screenshots_dir = @output_dir.join(screenshots_dirname).expand_path
+        @with_contents_dir = with_contents_dir
       end
     end
   end

lib/rundoc/version.rb

@@ -1,3 +1,3 @@
 module Rundoc
-  VERSION = "3.0.2"
+  VERSION = "3.1.0"
 end

test/integration/with_contents_flag_test.rb

@@ -0,0 +1,35 @@
+require "test_helper"
+
+class WithContentsFlagTest < Minitest::Test
+  def test_with_contents_flag
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        contents_dir = dir.join("contents").tap { |p| p.mkpath }
+        FileUtils.touch(contents_dir.join("file1.txt"))
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ ls
+          ```
+        EOF
+
+        refute dir.join(SUCCESS_DIRNAME).join("file1.txt").exist?
+
+        io = StringIO.new
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME),
+          with_contents_dir: contents_dir
+        ).call
+
+        doc = dir.join(SUCCESS_DIRNAME).join("README.md").read
+        assert_includes doc, "$ ls"
+        assert_includes doc, "file1.txt"
+      end
+    end
+  end
+end

test/test_helper.rb

@@ -23,6 +23,7 @@ def default_context(
     Rundoc::Context::Execution.new(
       output_dir: output_dir || Pathname("/dev/null"),
       source_path: source_path || Pathname("/dev/null"),
+      with_contents_dir: nil,
       screenshots_dirname: screenshots_dirname || Pathname("/dev/null")
     )
   end