rundoc 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89f953193be8aea0831e65e251a1d0cc8a3796573fe5818a6eb4ae2ed0e489d4
-  data.tar.gz: 9ea2f3a42906fa0c79cbb39862ec5300b4688dcce15df8991cf0a99e2d7c60da
+  metadata.gz: 7e89c8353e4727ae39613f24c38bf3a69f027c6d1e533e64e281a588405ff57f
+  data.tar.gz: 34df7f620c446901596deec889b9c8f785bd10e0441a54e1904b799ae9b8f0cd
 SHA512:
-  metadata.gz: 4aba6794da79ce27d6a4072e0cda4c7e2525030f0bd7c7925aaca8708a3adbd2632a0bb32c2ea451bc5f58ebc4a674ab4012ec6ddaeae7114ffbcefbafb53b35
-  data.tar.gz: fef87625649965fdd3dd5817e55d73299e1ebf67cfb3f9895c45d2c26b410af566f43540490a7c4ec7198b31f86d9c14079701b25981f7689b99644775f8e55f
+  metadata.gz: beb56a43157798ba53c4e63d715fd75892bc6d2b93bd0b8d379168c4dcc8807af3c31a5b8ac1a8af6215fa738bad6f8b4e2df525bae1c6590ef8bf7d3e94b29d
+  data.tar.gz: 8f6555c197fc600cc5cbf60af7d558213f50ec2a01b3d72f57e09eec628ba3169a512230b9ae106071afb2b536a6b7a314b3a8a832eb64e158565d977ab28e06

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## HEAD
 
+## 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)
+
 ## 3.0.1
 
 - Fix: Save in-progress work in the "failure" directory when the rundoc command is interrupted via a signal such as `SIGTERM` (https://github.com/zombocom/rundoc/pull/67)

data/lib/rundoc/cli.rb

@@ -24,6 +24,7 @@ module Rundoc
       on_success_dir: nil,
       on_failure_dir: nil,
       output_filename: nil,
+      with_contents_dir: nil,
       screenshots_dirname: nil
     )
       @io = io
@@ -37,6 +38,7 @@ module Rundoc
       @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 @@ module Rundoc
 
       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(
@@ -152,7 +164,7 @@ module Rundoc
         output = begin
           parser.to_md
         rescue StandardError, SignalException => e
-          warn "Received exception: #{e.inspect}, cleaning up before re-raise"
+          io.puts "Received exception: #{e.inspect}, cleaning up before re-raise"
           on_fail
           raise e
         end
@@ -190,6 +202,8 @@ module Rundoc
         from: execution_context.output_dir,
         to: on_failure_dir
       )
+
+      on_failure_dir.join("RUNDOC_FAILED.md").write(Rundoc::CodeSection.partial_result_to_doc)
     end
 
     private def on_success(output)

data/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 @@ module Rundoc
           @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

data/lib/rundoc/code_command/background/process_spawn.rb

@@ -43,7 +43,7 @@ class Rundoc::CodeCommand::Background
       @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 @@ class Rundoc::CodeCommand::Background
         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?

data/lib/rundoc/code_command/background/start.rb

@@ -15,6 +15,7 @@ class Rundoc::CodeCommand::Background
         log: log,
         out: out
       )
+      puts "Spawning commmand: `#{@spawn.command}`"
       ProcessSpawn.add(@name, @spawn)
     end
 

data/lib/rundoc/code_section.rb

@@ -30,6 +30,9 @@ module Rundoc
     AUTOGEN_WARNING = "\n<!-- STOP. This document is autogenerated. Do not manually modify. See the top of the doc for more details. -->"
     attr_accessor :original, :fence, :lang, :code, :commands, :keyword
 
+    PARTIAL_RESULT = []
+    PARTIAL_ENV = {}
+
     def initialize(match, keyword:, context:)
       @original = match.to_s
       @commands = []
@@ -40,6 +43,8 @@ module Rundoc
       @lang = match[:lang]
       @code = match[:contents]
       parse_code_command
+      PARTIAL_RESULT.clear
+      PARTIAL_ENV.clear
     end
 
     def render
@@ -69,10 +74,21 @@ module Rundoc
         tmp_result << code_output if code_command.render_result?
 
         result << tmp_result unless code_command.hidden?
+
+        PARTIAL_RESULT.replace(result)
+        PARTIAL_ENV.replace(env)
       end
 
       return "" if hidden?
 
+      self.class.to_doc(result: result, env: env)
+    end
+
+    def self.partial_result_to_doc
+      to_doc(result: PARTIAL_RESULT, env: PARTIAL_ENV)
+    end
+
+    def self.to_doc(result:, env:)
       array = [env[:before]]
 
       result.flatten!

data/lib/rundoc/context/execution.rb

@@ -9,13 +9,16 @@ module Rundoc
         # 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

data/lib/rundoc/version.rb

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

data/test/integration/failure_test.rb

@@ -0,0 +1,46 @@
+require "test_helper"
+
+class IntegrationFailureTest < Minitest::Test
+  def test_writes_to_dir_on_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir lol
+          :::>> $ touch lol/rofl.txt
+          :::>> $ touch does/not/exist.txt
+          ```
+        EOF
+
+        io = StringIO.new
+
+        error = nil
+        begin
+          Rundoc::CLI.new(
+            io: io,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        rescue => e
+          error = e
+        end
+
+        assert error
+        assert_includes error.message, "exited with non zero status"
+
+        refute dir.join(SUCCESS_DIRNAME).join("lol").exist?
+        refute dir.join(SUCCESS_DIRNAME).join("lol").join("rofl.txt").exist?
+
+        assert dir.join(FAILURE_DIRNAME).join("lol").exist?
+        assert dir.join(FAILURE_DIRNAME).join("lol").join("rofl.txt").exist?
+
+        doc = dir.join(FAILURE_DIRNAME).join("RUNDOC_FAILED.md").read
+        assert_includes doc, "$ mkdir lol"
+        assert_includes doc, "$ touch lol/rofl.txt"
+      end
+    end
+  end
+end

data/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

data/test/test_helper.rb

@@ -23,6 +23,7 @@ class Minitest::Test
     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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rundoc
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Richard Schneeman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-20 00:00:00.000000000 Z
+date: 2024-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -261,9 +261,11 @@ files:
 - test/fixtures/screenshot/rundoc.md
 - test/fixtures/simple_git/rundoc.md
 - test/integration/after_build_test.rb
+- test/integration/failure_test.rb
 - test/integration/print_test.rb
 - test/integration/require_test.rb
 - test/integration/website_test.rb
+- test/integration/with_contents_flag_test.rb
 - test/rundoc/cli_argument_parser_test.rb
 - test/rundoc/code_commands/append_file_test.rb
 - test/rundoc/code_commands/background_test.rb