rundoc 3.0.2 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87495a9fcbdf3fa9a146b633d84f62294bd400b32f806d975db0b372ce6c4f31
-  data.tar.gz: c50e2b6dbcbb2e313753d1341a17b56208118b10bd20462768348cae56cb3dda
+  metadata.gz: d21f4ac48ad2eab762969c03ce386aeb097f99162d38716e4736de44c9bbac83
+  data.tar.gz: 79f9be265a84d8474e3ed7d55d90781e9999790b6cf5e578943db89e0fec7ee9
 SHA512:
-  metadata.gz: 3e34467cf37d802daf82bb6fd8e81a4ecb4af426bc1645151e7d420dec131e4493b4e5f8ba78de3393bdc84a4de97dbc908434f4e1f06a895fc9002ca72611a5
-  data.tar.gz: 6971fa4915f79d81d1b6e6dd05f10e45e116f7388ae4c5ffd8b8ad1e9dc28be9c7882b11c6f315934b210281508fc17edb722969497fd951780befcb1d66eef2
+  metadata.gz: fcf456c89f09000ddeeaf7aa22654acf419f36294b9e88dec9735f9ec3fcab315085dd6ee97cbd63eb580078e009968219b5240a6fe7a6db4c022d1b878d97cb
+  data.tar.gz: 8e2ee0bd6fa26b8b8906ec9b2267a9e98feedc40b54dc53ca457937a7199865c2c6b7663837a067802426321fc93740da3038289ea516139a573a1e5679c8724

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## HEAD
 
+## 3.1.1
+
+- 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)

data/README.md

@@ -88,6 +88,7 @@ This will generate a project folder with your project in it, and a markdown `REA
   - [background.stop](#background)
   - [background.log.read](#background)
   - [background.log.clear](#background)
+  - [background.wait](#background)
 - Take screenshots
   - [website.visit](#screenshots)
   - [website.nav](#screenshots)
@@ -410,6 +411,13 @@ To start a process, pass in the command as the first arg, and give it a name (so
 :::>> background.start("rails server", name: "server")
 ```
 
+- Arguments
+  - name: Identifier of the background process, used in later invocations.
+  - wait (Optional): A string to wait for before continuing. This is useful to block moving on until an event happend such as a server was booted or web request was received. Also see `background.wait`
+  - timeout (Optional): A number of seconds to wait for a given string to be found in the logs.
+  - out (Optional): A bash redirect. Defaults to `2>&1` to merge stderr and stdout together.
+  - allow_fail (Optional): Set to `true` if the command exiting shouldn't halt doc generation. Poorly named, may be renamed in the future.
+
 You can make the background process wait until it receives a certain string in the logs. For instance to make sure that the server is fully booted:
 
 ```
@@ -422,18 +430,38 @@ You can stop the process by referencing the name:
 :::-- background.stop(name: "server")
 ```
 
+- Arguments
+  - name
+
 You can also get the log contents:
 
 ```
 :::>> background.log.read(name: "server")
 ```
 
+- Arguments
+  - name
+
 You can also truncate the logs:
 
 ```
 :::>> background.log.clear(name: "server")
 ```
 
+- Arguments
+  - name
+
+You can also wait for a given string to appear in the logs:
+
+```
+:::>> background.wait(name: "server", wait: "method=GET")
+```
+
+- Arguments
+  - name
+  - wait: Same as `background.start` a string value to look for before continuing.
+  - timeout: Maximum number of seconds to wait
+
 ## Screenshots
 
 You'll need selenium and `chromedriver` installed on your system to make screenshots work. On a mac you can run:

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(
@@ -191,7 +203,7 @@ module Rundoc
         to: on_failure_dir
       )
 
-      on_failure_dir.join("RUNDOC_FAILED.md").write(Rundoc::CodeSection.partial_result_to_doc)
+      on_failure_dir.join("RUNDOC_FAILED.md").write(Rundoc::Parser.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

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Rundoc
-  # holds code, parses and creates CodeCommand
+  # A code secttion respesents a block of fenced code
+  #
+  # A document can have multiple code sections
   class CodeSection
     class ParseError < StandardError
       def initialize(options = {})

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/parser.rb

@@ -1,4 +1,8 @@
 module Rundoc
+  # This poorly named class is responsible for taking in the raw markdown and running it
+  #
+  # It works by pulling out the code blocks (CodeSection), and putting them onto a stack.
+  # It then executes each in turn and records the results.
   class Parser
     DEFAULT_KEYWORD = ":::"
     INDENT_BLOCK = '(?<before_indent>(^\s*$\n|\A)(^(?:[ ]{4}|\t))(?<indent_contents>.*)(?<after_indent>[^\s].*$\n?(?:(?:^\s*$\n?)*^(?:[ ]{4}|\t).*[^\s].*$\n?)*))'
@@ -7,6 +11,7 @@ module Rundoc
     COMMAND_REGEX = ->(keyword) {
       /^#{keyword}(?<tag>(\s|=|-|>)?(=|-|>)?)\s*(?<command>(\S)+)\s+(?<statement>.*)$/
     }
+    PARTIAL_RESULT = []
 
     attr_reader :contents, :keyword, :stack, :context
 
@@ -17,6 +22,7 @@ module Rundoc
       @keyword = keyword
       @stack = []
       partition
+      PARTIAL_RESULT.clear
     end
 
     def to_md
@@ -27,13 +33,26 @@ module Rundoc
         else
           s
         end
+        PARTIAL_RESULT.replace(result)
       end
-      result.join("")
+
+      self.class.to_doc(result: result)
     rescue => e
       File.write("README.md", result.join(""))
       raise e
     end
 
+    def self.partial_result_to_doc
+      out = to_doc(result: PARTIAL_RESULT)
+      unfinished = CodeSection.partial_result_to_doc
+      out << unfinished if unfinished
+      out
+    end
+
+    def self.to_doc(result:)
+      result.join("")
+    end
+
     # split into [before_code, code, after_code], process code, and re-run until tail is empty
     def partition
       until contents.empty?

data/lib/rundoc/version.rb

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

data/test/integration/failure_test.rb

@@ -1,7 +1,58 @@
 require "test_helper"
 
 class IntegrationFailureTest < Minitest::Test
-  def test_writes_to_dir_on_failure
+  def test_writes_to_dir_on_failure_two_block
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir one
+          :::>> $ touch one/rofl.txt
+          ```
+
+          ```
+          :::>> $ mkdir two
+          :::>> $ touch two/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("two").exist?
+        refute dir.join(SUCCESS_DIRNAME).join("two").join("rofl.txt").exist?
+
+        assert dir.join(FAILURE_DIRNAME).join("two").exist?
+        assert dir.join(FAILURE_DIRNAME).join("two").join("rofl.txt").exist?
+
+        doc = dir.join(FAILURE_DIRNAME).join("RUNDOC_FAILED.md").read
+        assert_includes doc, "$ mkdir one"
+        assert_includes doc, "$ touch one/rofl.txt"
+
+        assert_includes doc, "$ mkdir two"
+        assert_includes doc, "$ touch two/rofl.txt"
+      end
+    end
+  end
+
+  def test_writes_to_dir_on_failure_one_block
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         dir = Pathname(dir)

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.2
+  version: 3.1.1
 platform: ruby
 authors:
 - Richard Schneeman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-20 00:00:00.000000000 Z
+date: 2024-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -265,6 +265,7 @@ files:
 - 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