rundoc 2.0.1 → 3.0.0

data/lib/rundoc/cli_argument_parser.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "optparse"
+
+module Rundoc
+  # This class is responsible for parsing the command line arguments and generating a Cli instance
+  #
+  # Example:
+  #
+  #   cli = CLIArgumentParser.new(argv: ARGV).to_cli
+  #   cli.call
+  #
+  class CLIArgumentParser
+    attr_reader :io, :env, :exit_obj, :options, :argv
+
+    def initialize(
+      argv:,
+      io: $stderr,
+      env: ENV,
+      exit_obj: Kernel
+    )
+      @io = io
+      @env = env
+      @argv = argv
+      @options = {}
+      @exit_obj = exit_obj
+    end
+
+    def call
+      source_file = argv.first
+      if source_file.nil? || source_file == "help"
+        parser.parse! ["--help"]
+        return
+      else
+        parser.parse! argv
+        return if options[:exit]
+      end
+
+      source_path = Pathname(source_file)
+      if !source_path.exist?
+        @io.puts "No such file `#{source_path.expand_path}`"
+        exit_obj.exit(1)
+        return
+      elsif !source_path.file?
+        @io.puts "Path is not a file. Expected `#{source_path.expand_path}` to be a file, but it was not."
+        exit_obj.exit(1)
+        return
+      end
+
+      options[:io] = io
+      options[:source_path] = source_path
+
+      self
+    end
+
+    private def parser
+      @parser ||= OptionParser.new do |opts|
+        opts.banner = <<~EOF
+          Usage: $ rundoc [options] <path/to/RUNDOC.md>
+
+          Reads a custom markdown file and executes the code blocks within it to produce a tutorial with real world outputs embedded.
+
+          Produces:
+
+            - A directory with any generated files
+            - A #{CLI::DEFAULTS::OUTPUT_FILENAME} file with the generated output
+            - A screenshots directory with any screenshots taken
+
+          ## Example
+
+          A rundoc file:
+
+            ~$ cat path/to/RUNDOC.md
+            ```
+            :::>> $ echo "hello world"
+            :::>> $ touch grass.txt
+            ```
+
+          Is executed with the rundoc command
+
+            ~$ rundoc path/to/RUNDOC.md
+            # ...
+
+          Produces files on disk:
+
+            ~$ ls path/to/#{CLI::DEFAULTS::ON_SUCCESS_DIR}
+            #{CLI::DEFAULTS::OUTPUT_FILENAME}
+            grass.txt
+
+          And replaces the rundoc syntax with the result of the real output:
+
+            ~$ cat path/to/#{CLI::DEFAULTS::ON_SUCCESS_DIR}/#{CLI::DEFAULTS::OUTPUT_FILENAME}
+            ```
+            $ echo "hello world"
+            hello world
+            $ touch grass.txt
+            ```
+
+          ## Options
+
+          > Note: Current working directory is abbreviated CWD
+
+        EOF
+
+        opts.on("--help", "Prints this help output.") do |_|
+          @io.puts opts
+          options[:exit] = true
+          @exit_obj.exit(0)
+        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
+
+        opts.on("--on-failure-dir <dir>", "Failure dir, relative to CWD i.e. `<rundoc.md/dir>/#{CLI::DEFAULTS::ON_FAILURE_DIR}/`.") do |v|
+          options[:on_failure_dir] = v
+        end
+
+        opts.on("--dotenv-path <path>", "Environment variable file, relative to CWD. i.e. `<rundoc.md/dir>/.env`.") do |v|
+          options[:dotenv_path] = v
+        end
+
+        opts.on("--output-filename <name>", "Name of the generated markdown file i.e. `#{CLI::DEFAULTS::OUTPUT_FILENAME}`.") do |v|
+          options[:output_filename] = v
+        end
+
+        opts.on("--screenshots-dirname <name>", "Name of screenshot dir i.e. `#{CLI::DEFAULTS::SCREENSHOTS_DIR}`.") do |v|
+          options[:screenshots_dirname] = v
+        end
+
+        opts.on("--force", "Delete contents of the success/failure dirs even if they're not empty.") do |v|
+          options[:force] = v
+        end
+      end
+    end
+  end
+end
+
+require_relative "cli"

data/lib/rundoc/code_command/bash.rb

@@ -40,8 +40,15 @@ class Rundoc::CodeCommand::Bash < Rundoc::CodeCommand
     IO.popen(cmd, "w+") do |io|
       io << stdin if stdin
       io.close_write
-      result = sanitize_escape_chars io.read
+
+      until io.eof?
+        buffer = io.gets
+        puts "    #{buffer}"
+
+        result << sanitize_escape_chars(buffer)
+      end
     end
+
     unless $?.success?
       raise "Command `#{@line}` exited with non zero status: #{result}" unless keyword.to_s.include?("fail")
     end

data/lib/rundoc/code_command/rundoc/depend_on.rb

@@ -4,30 +4,7 @@ class ::Rundoc::CodeCommand
       # Pass in the relative path of another rundoc document in order to
       # run all of it's commands (but not to )
       def initialize(path)
-        raise "Path must be relative (i.e. start with `.` or `..`. #{path.inspect} does not" unless path.start_with?(".")
-        @path = Pathname.new(path)
-      end
-
-      def to_md(env = {})
-        ""
-      end
-
-      def call(env = {})
-        current_path = Pathname.new(env[:document_path]).dirname
-        document_path = @path.expand_path(current_path)
-        # Run the commands, but do not
-        puts "rundoc.depend_on: Start executing #{@path.to_s.inspect}"
-        output = Rundoc::Parser.new(document_path.read, document_path: document_path.to_s).to_md
-        puts "rundoc.depend_on: Done executing #{@path.to_s.inspect}, discarding intermediate document"
-        output
-      end
-
-      def hidden?
-        true
-      end
-
-      def not_hidden?
-        !hidden?
+        raise "rundoc.depend_on has been removed, use `:::-- rundoc.require` instead"
       end
     end
   end

data/lib/rundoc/code_command/rundoc/require.rb

@@ -14,20 +14,26 @@ class ::Rundoc::CodeCommand
       end
 
       def call(env = {})
-        env[:replace] ||= +""
-        current_path = Pathname.new(env[:document_path]).dirname
-        document_path = @path.expand_path(current_path)
+        document_path = @path.expand_path(env[:context].source_dir)
 
         puts "rundoc.require: Start executing #{@path.to_s.inspect}"
-        output = Rundoc::Parser.new(document_path.read, document_path: document_path.to_s).to_md
-        puts "rundoc.require: Done executing #{@path.to_s.inspect}, putting contents into document"
+        output = Rundoc::Parser.new(
+          document_path.read,
+          context: env[:context]
+        ).to_md
+
+        if render_result?
+          puts "rundoc.require: Done executing #{@path.to_s.inspect}, putting contents into document"
+          env[:before] << output
+        else
+          puts "rundoc.require: Done executing #{@path.to_s.inspect}, quietly"
+        end
 
-        env[:replace] << output
         ""
       end
 
       def hidden?
-        true
+        !render_result?
       end
 
       def not_hidden?

data/lib/rundoc/code_command/website/driver.rb

@@ -48,23 +48,25 @@ class Rundoc::CodeCommand::Website
       attr_reader :tasks
     end
 
-    def safe_eval(code)
+    def safe_eval(code, env = {})
       @driver.send(:eval, code)
     rescue => e
       msg = +""
       msg << "Error running code #{code.inspect} at #{current_url.inspect}\n"
       msg << "saving a screenshot to: `tmp/error.png`"
       puts msg
-      session.save_screenshot("tmp/error.png")
+      error_path = env[:context].screenshots_dir.join("error.png")
+      session.save_screenshot(error_path)
       raise e
     end
 
-    def screenshot(upload: false)
+    def screenshot(screenshots_dir:, upload: false)
       @driver.resize_window_to(@driver.current_window_handle, @width, @height)
-      FileUtils.mkdir_p("tmp/rundoc_screenshots")
+      FileUtils.mkdir_p(screenshots_dir)
       file_name = self.class.next_screenshot_name
-      file_path = "tmp/rundoc_screenshots/#{file_name}"
+      file_path = screenshots_dir.join(file_name)
       session.save_screenshot(file_path)
+      puts "Screenshot saved to #{file_path}"
 
       return file_path unless upload
 

data/lib/rundoc/code_command/website/navigate.rb

@@ -11,7 +11,7 @@ class Rundoc::CodeCommand::Website
 
     def call(env = {})
       puts "website.navigate [#{@name}]: #{contents}"
-      @driver.safe_eval(contents)
+      @driver.safe_eval(contents, env)
       ""
     end
 

data/lib/rundoc/code_command/website/screenshot.rb

@@ -11,8 +11,13 @@ class Rundoc::CodeCommand::Website
 
     def call(env = {})
       puts "Taking screenshot: #{@driver.current_url}"
-      filename = @driver.screenshot(upload: @upload)
-      env[:replace] = "![Screenshot of #{@driver.current_url}](#{filename})"
+      filename = @driver.screenshot(
+        upload: @upload,
+        screenshots_dir: env[:context].screenshots_dir
+      )
+
+      relative_filename = filename.relative_path_from(env[:context].output_dir)
+      env[:before] << "![Screenshot of #{@driver.current_url}](#{relative_filename})"
       ""
     end
 

data/lib/rundoc/code_command/website/visit.rb

@@ -28,7 +28,7 @@ class Rundoc::CodeCommand::Website
       @driver.scroll(@scroll) if @scroll
 
       return "" if contents.nil? || contents.empty?
-      @driver.safe_eval(contents)
+      @driver.safe_eval(contents, env)
 
       ""
     end

data/lib/rundoc/code_section.rb

@@ -28,12 +28,12 @@ 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
 
-    def initialize(match, options = {})
+    def initialize(match, keyword:, context:)
       @original = match.to_s
       @commands = []
       @stack = []
-      @keyword = options[:keyword] or raise "keyword is required"
-      @document_path = options[:document_path]
+      @keyword = keyword
+      @context = context
       @fence = match[:fence]
       @lang = match[:lang]
       @code = match[:contents]
@@ -48,7 +48,7 @@ module Rundoc
       env[:fence_end] = "#{fence}#{AUTOGEN_WARNING}"
       env[:before] = []
       env[:after] = []
-      env[:document_path] = @document_path
+      env[:context] = @context
 
       @stack.each do |s|
         unless s.respond_to?(:call)
@@ -69,8 +69,6 @@ module Rundoc
         result << tmp_result unless code_command.hidden?
       end
 
-      return env[:replace] if env[:replace]
-
       return "" if hidden?
 
       array = [env[:before]]

data/lib/rundoc/context/after_build.rb

@@ -0,0 +1,14 @@
+module Rundoc
+  module Context
+    # Public interface for the `Rundoc.after_build` proc
+    class AfterBuild
+      attr_reader :output_markdown_path, :screenshots_dir, :output_dir
+
+      def initialize(output_markdown_path:, screenshots_dir:, output_dir:)
+        @output_dir = output_dir
+        @screenshots_dir = screenshots_dir
+        @output_markdown_path = output_markdown_path
+      end
+    end
+  end
+end

data/lib/rundoc/context/execution.rb

@@ -0,0 +1,22 @@
+module Rundoc
+  module Context
+    # Holds configuration for the currently executing script
+    class Execution
+      # The path to the source file
+      attr_reader :source_path,
+        # The directory containing the source file
+        :source_dir,
+        # The directory we are actively manipulating
+        :output_dir,
+        # Directory to store screenshots, relative to output_dir
+        :screenshots_dir
+
+      def initialize(source_path:, output_dir:, screenshots_dirname:)
+        @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
+      end
+    end
+  end
+end

data/lib/rundoc/parser.rb

@@ -8,10 +8,10 @@ module Rundoc
       /^#{keyword}(?<tag>(\s|=|-|>)?(=|-|>)?)\s*(?<command>(\S)+)\s+(?<statement>.*)$/
     }
 
-    attr_reader :contents, :keyword, :stack
+    attr_reader :contents, :keyword, :stack, :context
 
-    def initialize(contents, keyword: DEFAULT_KEYWORD, document_path: nil)
-      @document_path = document_path
+    def initialize(contents, context:, keyword: DEFAULT_KEYWORD)
+      @context = context
       @contents = contents
       @original = contents.dup
       @keyword = keyword
@@ -41,7 +41,11 @@ module Rundoc
         @stack << head unless head.empty?
         unless code.empty?
           match = code.match(CODEBLOCK_REGEX)
-          @stack << CodeSection.new(match, keyword: keyword, document_path: @document_path)
+          @stack << CodeSection.new(
+            match,
+            keyword: keyword,
+            context: context
+          )
         end
         @contents = tail
       end

data/lib/rundoc/version.rb

@@ -1,3 +1,3 @@
 module Rundoc
-  VERSION = "2.0.1"
+  VERSION = "3.0.0"
 end

data/lib/rundoc.rb

@@ -48,9 +48,9 @@ module Rundoc
     yield self
   end
 
-  def run_after_build
+  def run_after_build(context)
     @after_build_block ||= []
-    @after_build_block.each(&:call)
+    @after_build_block.each { |block| block.call(context) }
   end
 
   def after_build(&block)
@@ -68,7 +68,7 @@ module Rundoc
     @sensitive.merge!(sensitive)
   end
 
-  def sanitize(doc)
+  def sanitize!(doc)
     return doc if @sensitive.nil?
     @sensitive.each do |sensitive, replace|
       doc.gsub!(sensitive.to_s, replace)
@@ -76,11 +76,19 @@ module Rundoc
     doc
   end
 
-  attr_accessor :project_root
+  attr_reader :project_root
+
+  def project_root=(root)
+    raise <<~MSG
+      Setting Rundoc.project_root is now a no-op
+
+      If you want to manipulate the directory structure, use `Rundoc.after_build` instead.
+    MSG
+  end
 end
 
 require "rundoc/parser"
 require "rundoc/code_section"
 require "rundoc/code_command"
 require "rundoc/peg_parser"
-require "rundoc/cli"
+require "rundoc/cli_argument_parser"

data/rundoc.gemspec

@@ -29,4 +29,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "mocha"
   gem.add_development_dependency "minitest"
   gem.add_development_dependency "standard"
+  gem.add_development_dependency "simplecov"
 end

data/test/fixtures/cnb/ruby/download.md

@@ -0,0 +1,22 @@
+## Download an example Ruby on Rails application
+
+How do you configure a CNB? Give them an application. While Dockerfile is procedural, buildpacks, are declarative. A buildpack will determine what your application needs to function by inspecting the code on disk.
+
+For this example, we're using a pre-built Ruby on Rails application. Download it now:
+
+```
+:::>- $ git clone https://github.com/heroku/ruby-getting-started
+:::>- $ cd ruby-getting-started
+```
+
+Verify you're in the correct directory:
+
+```
+:::>> $ ls
+```
+
+This tutorial was built using the following commit SHA:
+
+```
+:::>> $ git log --oneline | head -n1
+```

data/test/fixtures/cnb/ruby/image_structure.md

@@ -0,0 +1,34 @@
+## Image structure under the hood
+
+> [!NOTE]
+> Skip this section if you want to try building your application with CNBs and learn about container structure later.
+
+If you’re an advanced `Dockerfile` user you might be interested in learning more about the internal structure of the image on disk. You can access the image disk interactively by using the `bash` docker command above.
+
+If you view the root directory `/` you’ll see there is a `layers` folder. Every buildpack that executes gets a unique folder. For example:
+
+```
+:::>> $ docker run --rm my-image-name "ls /layers | grep ruby"
+```
+
+Individual buildpacks can compose multiple layers from their buildpack directory. For example you can see that `ruby` binary is present within that ruby buildpack directory:
+
+```
+:::>> $ docker run --rm my-image-name "which ruby"
+```
+
+OCI images are represented as sequential modifications to disk. By scoping buildpack disk modifications to their own directory, the CNB API guarantees that changes to a layer in one buildpack will not affect the contents of disk to another layer. This means that OCI images produced by CNBs are rebaseable by default, while those produced by Dockerfile are not.
+
+We saw before how the image booted a web server by default. This is accomplished using an entrypoint. In another terminal outside of the running container you can view that entrypoint:
+
+```
+:::>> $ docker inspect my-image-name | grep '"Entrypoint": \[' -A2
+```
+
+From within the image, you can see that file on disk:
+
+```
+:::>> $ docker run --rm my-image-name "ls /cnb/process/"
+```
+
+While you might not need this level of detail to build and run an application with Cloud Native Buildpacks, it is useful to understand how they’re structured if you ever want to write your own buildpack.

data/test/fixtures/cnb/ruby/intro.md

@@ -0,0 +1,5 @@
+# Heroku Ruby Cloud Native Buildpack (CNB) Tutorial
+
+Build a Ruby on Rails application image in 5 minutes, no Dockerfile required.
+
+At the end of this tutorial, you'll have a working [OCI image](https://opencontainers.org/) of a Ruby on Rails application that can run locally. You will learn about the Cloud Native Buildpack (CNB) ecosystem, and how to utilize the [pack CLI](https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/) to build images without the need to write or maintain a Dockerfile.

data/test/fixtures/cnb/ruby/multiple_langs.md

@@ -0,0 +1,43 @@
+## Configuring multiple languages
+
+Language support is provided by individual buildpacks that are shipped with the builder. The above example uses the `heroku/ruby` buildpack which is [visible on GitHub](https://github.com/heroku/buildpacks-ruby). When you execute `pack build` with a builder, every buildpack has the opportunity to "detect" if it should execute against that project. The `heroku/ruby` buildpack looks for a `Gemfile.lock` in the root of the project and if found, knows how to detect a Ruby version and install dependencies.
+
+In addition to this auto-detection behavior, you can specify buildpacks through the `--buildpack` flag with the `pack` CLI or through a [project.toml](https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/specify-buildpacks/) file at the root of your application.
+
+For example, if you wanted to install both Ruby, NodeJS and Python you could create a `project.toml` file in the root of your application and specify those buildpacks.
+
+```toml
+:::>> file.write project.toml
+[_]
+schema-version = "0.2"
+id = "sample.ruby+python.app"
+name = "Sample Ruby & Python App"
+version = "1.0.0"
+
+[[io.buildpacks.group]]
+uri = "heroku/python"
+
+[[io.buildpacks.group]]
+uri = "heroku/nodejs"
+
+[[io.buildpacks.group]]
+uri = "heroku/ruby"
+
+[[io.buildpacks.group]]
+uri = "heroku/procfile"
+```
+
+Ensure that a `requirements.txt` file, a `package.json` file and a `Gemfile.lock` file all exist and then build your application:
+
+```
+:::>> $ touch requirements.txt
+:::>> $ pack build my-image-name --path .
+```
+
+You can run the image and inspect everything is installed as expected:
+
+```
+$ docker run -it --rm my-image-name bash
+$ which python
+:::-> $ docker run --rm my-image-name "which python"
+```

data/test/fixtures/cnb/ruby/rundoc.md

@@ -0,0 +1,48 @@
+
+```
+:::>> rundoc.require "./intro.md"
+```
+
+```
+:::>> rundoc.require "../shared/install_pack.md"
+```
+
+```
+:::>> rundoc.require "../shared/configure_builder.md"
+```
+
+```
+:::>> rundoc.require "../shared/what_is_a_builder.md"
+```
+
+```
+:::>> rundoc.require "./download.md"
+```
+
+```
+:::>> rundoc.require "../shared/pack_build.md"
+```
+
+```
+:::>> rundoc.require "./what_is_pack_build.md"
+```
+
+```
+:::>> rundoc.require "../shared/use_the_image.md"
+```
+
+```
+:::>> rundoc.require "./image_structure.md"
+```
+
+```
+:::>> rundoc.require "../shared/call_to_action.md"
+```
+
+```
+:::>> rundoc.require "./multiple_langs.md"
+```
+
+```
+:::>> rundoc.require "../shared/procfile.md"
+```

data/test/fixtures/cnb/ruby/what_is_pack_build.md

@@ -0,0 +1,18 @@
+## What does `pack build` do?
+
+> [!NOTE]
+> Skip ahead if you want to run the application first and get into the details later.
+
+When you run `pack build` with a builder, each buildpack runs a detection script to determine if it should be eligible to build the application. In our case the `heroku/ruby` buildpack found a `Gemfile.lock` file and `heroku/nodejs-engine` buildpack found a `package.json` file on disk. As a result, both buildpacks have enough information to install Ruby and Node dependencies. You can view a list of the buildpacks used in the output above:
+
+```
+:::-> $ grep DETECTING -A5 ./build_output.txt
+```
+
+After the detect phase, each buildpack will execute. Buildpacks can inspect your project, install files to disk, run commands, write environment variables, [and more](https://buildpacks.io/docs/for-buildpack-authors/). You can see some examples of that in the output above. For example, the Ruby buildpack installs dependencies from the `Gemfile` automatically:
+
+```
+:::-> $ grep "bundle install" -m1 -A10 ./build_output.txt
+```
+
+If you’re familiar with Dockerfile you might know that [many commands in a Dockerfile will create a layer](https://dockerlabs.collabnix.com/beginners/dockerfile/Layering-Dockerfile.html). Buildpacks also use layers, but the CNB buildpack API provides for fine grained control over what exactly is in these layers and how they’re composed. Unlike Dockerfile, all images produced by CNBs [can be rebased](https://tag-env-sustainability.cncf.io/blog/2023-12-reduce-reuse-rebase-buildpacks/#reduce-reuserebase). The CNB api also improves on many of the pitfalls outlined in the satirical article [Write a Good Dockerfile in 19 'Easy' Steps](https://jkutner.github.io/2021/04/26/write-good-dockerfile.html).

data/test/fixtures/cnb/shared/call_to_action.md

@@ -0,0 +1,11 @@
+## Try CNBs out on your application
+
+So far we've learned that CNBs are a declarative interface for producing OCI images (like docker). They aim to be no to low configuration and once built, you can interact with them like any other image.
+
+For the next step, we encourage you to try running `pack` with the Heroku builder against your application and let us know how it went. We encourage you to share your experience by [opening a discussion](https://github.com/heroku/buildpacks/discussions) and walking us through what happened:
+
+- What went well?
+- What could be better?
+- Do you have any questions?
+
+We are actively working on our Cloud Native Buildpacks and want to hear about your experience. The documentation below covers some intermediate-level topics that you might find helpful.

data/test/fixtures/cnb/shared/configure_builder.md

@@ -0,0 +1,23 @@
+## Configure the default pack builder
+
+Once `pack` is installed, the only configuration you'll need for this tutorial is to set a default builder:
+
+```
+:::>> $ pack config default-builder heroku/builder:22
+```
+
+You can view your default builder at any time:
+
+```
+:::>> $ pack config default-builder
+```
+
+The following tutorial is built on amd64 architecture (also known as x86). If you are building on a machine with different architecture (such as arm64/aarch64 for a Mac) you will need to tell Docker to use `linux/amd64` architecture. You can do this via a `--platform linux/amd64` flag or by exporting an environment variable:
+
+```
+$ export DOCKER_DEFAULT_PLATFORM=linux/amd64
+:::-- rundoc.configure
+# Needed because all `$` commands are run as separate isolated processes
+
+ENV["DOCKER_DEFAULT_PLATFORM"] = "linux/amd64"
+```