rundoc 6.0.0 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 498d5109daa7abb733fc5c27cf583bb1c84cc7b92bbccaaf9e005a51a6ec0555
-  data.tar.gz: fc72016241033a945486b5fa893b3f2cad0c8b3c7a2c44eab3f964adb7308f9e
+  metadata.gz: 30dcb03fc239fe1ddd02618341f780c8158ec145646049df7b597206dd7692db
+  data.tar.gz: c31c17bfa5997dc0c79b218e42493d719f6f19d26c1bc758f7d17f24bbe8d996
 SHA512:
-  metadata.gz: 5af654672de3e6051ec46377052c55b55207ce13eb29cf977d1cf793291e953d28e842fd79b0f0972f8eb83a98c6671c1834a5ac75f20da795eb686a99a02c52
-  data.tar.gz: b2acdf08759aa0c6f73410a00a4ad387da198f1f4497228c69d27dd799799e12107cc421c8f3fd5242f9517dbfd2565e71b56e2b3a6ffd77ffd879906c902d65
+  metadata.gz: d1c17df9586e3c8d767f8fa79c3d8afebddf5a84c09ae6cbdee14286bb184ee7d51c0ada0827a4dd8a0d480266b63bc1713872200d841b5ae0d5a0af482c2f20
+  data.tar.gz: a3e244880fe064cb86360953f8b3ca4e6b3569201f9bc0c96287686dd99a17a4c59cb3122160a4024b37808e98265758dd40290643cdbb84b0f5826fce5e234c

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## HEAD
 
+## 7.0.0
+
+- Changed: Shell commands now run under `bash -eo pipefail` instead of `/bin/sh`. This surfaces failures in pipelines and compound commands that were previously swallowed. See the README for details on SIGPIPE interactions.
+
 ## 6.0.0
 
 - Added: `rundoc.ensure_later(dir: :cwd)` command to register cleanup blocks that run on every build (success and failure). Useful for guaranteed resource teardown (e.g., destroying Heroku apps). Multiple blocks execute in order; failures in one block do not stop the rest.

data/README.md

@@ -259,6 +259,8 @@ However this command would fall on its face:
 
 These custom commands are kept to a minimum, and for the most part behave as you would expect them to. Write your docs as you normally would and check the output frequently.
 
+Shell commands run under `bash -eo pipefail` to catch silent failures in pipelines and compound commands. See [Bash Error Handling](#bash-error-handling) for details and SIGPIPE caveats.
+
 Running shell commands like this can be very powerful, you'll likely want more control of how you manipulate files in your project. To do this you can use the `file.` namespace:
 
 ## Dynamic command templating
@@ -719,6 +721,93 @@ The output of this will not be included in the document. Multiple ensure blocks
 
 If a build is successful, but an `ensure_later` block fails, the build will be considered a failure. A failure in one block will not stop the rest from executing.
 
+## Bash Error Handling
+
+### Bash `set -eo pipefail` explained
+
+Bash error behavior is configurable. Rundoc uses `set -eo pipefail` to catch common problems not caught by the default error mode.
+
+If a failing command is piped to a valid command, by default bash will "hide" the failure by returning a zero (success) exit code:
+
+```term
+$ bash -c "cat does-not-exist | head -n1"
+cat: does-not-exist: No such file or directory
+$ echo $?
+0
+```
+
+With `-o pipefail`, the pipeline reports the exit status of the last command that failed rather than the last command in the pipe. With `-e`, bash exits immediately when a command fails. Together, `-eo pipefail` ensures a failing command's exit status is not hidden. Here, the exit code `1` comes from `cat` failing to open a file that doesn't exist:
+
+```term
+$ bash -eo pipefail -c "cat does-not-exist | head -n1"
+cat: does-not-exist: No such file or directory
+$ echo $?
+1
+```
+
+A similar scenario is when multiple commands are given on one line separated by a semicolon. Without `-e`, bash continues past the failure:
+
+```term
+$ bash -c "cat does-not-exist; echo 'done'"
+cat: does-not-exist: No such file or directory
+done
+$ echo $?
+0
+```
+
+With `-e`, bash exits immediately after the failing command:
+
+```term
+$ bash -eo pipefail -c "cat does-not-exist; echo 'done'"
+cat: does-not-exist: No such file or directory
+$ echo $?
+1
+```
+
+These settings help prevent silent failures from slipping through your Rundoc scripts.
+
+### Bash SIGPIPE
+
+Tools like `head -n1` and `grep -m1 "value"` read only part of their input and then exit. When the upstream process next tries to write to the now-closed pipe, the kernel delivers a `SIGPIPE` signal to terminate it. This behavior is useful when the input is a never-ending stream but you only need a subset:
+
+```term
+$ bash -c 'yes "output" | head -n1'
+output
+$ echo $?
+0
+```
+
+However, this behavior negatively interacts with `set -eo pipefail`. Even though `head -n1` successfully produced its output and the command appears to run cleanly, `pipefail` reports the upstream process's SIGPIPE termination as a non-zero exit:
+
+```term
+$ bash -eo pipefail -c 'yes "output" | head -n1'
+output
+$ echo $?
+141
+```
+
+If the input is fully buffered (such as reading from a small file), `head` can finish before the writer needs to write again, so SIGPIPE is never triggered. That means `cat small-file.txt | head -n1` is reasonably safe, but this behavior can surface with larger files:
+
+```term
+$ tmpfile=$(mktemp)
+$ seq 1 200000 > "$tmpfile"
+$ bash -eo pipefail -c "cat $tmpfile | head -n1"
+1
+$ echo $?
+141
+```
+
+This SIGPIPE behavior can cause your rundoc script to exit early when you aren't expecting it.
+
+You can rewrite some commands to take a file directly. For example, `cat Gemfile | head -n 5` can be rewritten as `head -n 5 Gemfile` without SIGPIPE risk.
+
+Here are common commands that can trigger a SIGPIPE:
+
+- `head` with `-n <N>` or `-c <N>`
+- `grep` with `-m <N>` (max count)
+- `sed <N>q` (quit after N lines)
+- `awk` with `{exit}` — e.g., rewrite `awk '/^Start/ {flag=1} /^End/ {exit} flag'` without exit as `awk '/^Start/ {flag=1} /^End/ {flag=0} flag'`
+
 ## Writing a new command
 
 > Note: This is an advanced topic and this interface is unstable.

data/lib/rundoc/code_command/bash.rb

@@ -45,13 +45,18 @@ class Rundoc::CodeCommand::BashRunner
   end
 
   def shell(cmd, stdin = nil)
-    cmd = "(#{cmd}) 2>&1"
     msg = "Running: $ '#{cmd}'"
     msg << " with stdin: '#{stdin.inspect}'" if stdin && !stdin.empty?
     io.puts msg
 
     result = +""
-    IO.popen(cmd, "w+") do |pipe|
+    # -e: Abort on first failure in compound commands (e.g. `bundle install; echo done`)
+    #     so the exit status reflects the real failure, not a trailing success.
+    # -o pipefail: Report the first failure in a pipeline (e.g. `git push | tee log`)
+    #     instead of only the last command's exit status.
+    # -u (nounset) is intentionally omitted: tutorial commands routinely
+    #     reference environment variables that may not be set.
+    IO.popen(["bash", "-eo", "pipefail", "-c", cmd, err: [:child, :out]], "w+") do |pipe|
       pipe << stdin if stdin
       pipe.close_write
 

data/lib/rundoc/code_command/rundoc/ensure_later.rb

@@ -22,7 +22,7 @@ module ::Rundoc::CodeCommand
       end
 
       def to_s
-        @dir
+        @dir.to_s
       end
     end
 

data/lib/rundoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rundoc
-  VERSION = "6.0.0"
+  VERSION = "7.0.0"
 end

data/test/integration/ensure_later_test.rb

@@ -332,4 +332,34 @@ class IntegrationEnsureLaterTest < Minitest::Test
       end
     end
   end
+
+  def test_log_output_shows_dir_mode_name
+    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 "hello"
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        io = StringIO.new
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        output = io.string
+        assert_includes output, "Registering ensure_later block (dir: cwd => /"
+      end
+    end
+  end
 end

data/test/rundoc/code_commands/bash_test.rb

@@ -25,6 +25,30 @@ class BashTest < Minitest::Test
     end
   end
 
+  def test_pipefail_catches_early_failure
+    command = "false | true"
+    bash = Rundoc::CodeCommand::BashRunner.new(
+      render_command: false,
+      render_result: false,
+      io: StringIO.new,
+      user_args: Rundoc::CodeCommand::BashArgs.new(command)
+    )
+    error = assert_raises(RuntimeError) { bash.call }
+    assert_match(/exited with non zero status/, error.message)
+  end
+
+  def test_errexit_catches_compound_command_failure
+    command = "false; echo done"
+    bash = Rundoc::CodeCommand::BashRunner.new(
+      render_command: false,
+      render_result: false,
+      io: StringIO.new,
+      user_args: Rundoc::CodeCommand::BashArgs.new(command)
+    )
+    error = assert_raises(RuntimeError) { bash.call }
+    assert_match(/exited with non zero status/, error.message)
+  end
+
   def test_stdin
     command = "tail -n 2"
     bash = Rundoc::CodeCommand::BashRunner.new(

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rundoc
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 7.0.0
 platform: ruby
 authors:
 - Richard Schneeman
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -304,6 +305,7 @@ homepage: https://github.com/schneems/rundoc
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -318,7 +320,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: RunDOC generates runable code from docs
 test_files: []