rundoc 2.0.1 → 3.0.0

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

@@ -0,0 +1,14 @@
+## Install the pack CLI
+
+We assume you have [docker installed](https://docs.docker.com/engine/install/) and a working copy [of git](https://github.com/git-guides/install-git). Next, you will need to install the CLI tool for building CNBs, [pack CLI](https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/). If you're on a Mac you can install it via Homebrew:
+
+```
+:::-> print.text
+$ brew install buildpacks/tap/pack
+```
+
+Ensure that `pack` is installed correctly:
+
+```
+:::>> $ pack --version
+```

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

@@ -0,0 +1,20 @@
+## Build the application image with the pack CLI
+
+Now build an image named `my-image-name` by executing the heroku builder against the application by running the
+`pack build` command:
+
+```
+$ pack build my-image-name --path .
+:::-- $ docker rmi -f my-image-name
+:::-- $ pack build my-image-name --path . 2>&1 | tee build_output.txt
+:::-> $ cat build_output.txt
+```
+
+> [!NOTE]
+> Your output may differ.
+
+Verify that you see “Successfully built image my-image-name” at the end of the output. And verify that the image is present locally:
+
+```
+:::>> $ docker image ls --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" | grep my-image-name
+```

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

@@ -0,0 +1,13 @@
+## Configuring your web process with the Procfile
+
+Most buildpacks rely on existing community standards to allow you to configure your application declaratively. They can also implement custom logic based on file contents on disk or environment variables present at build time.
+
+The `Procfile` is a configuration file format that was [introduced by Heroku in 2011](https://devcenter.heroku.com/articles/procfile), you can now use this behavior on your CNB-powered application via the `heroku/procfile`, which like the rest of the buildpacks in our builder [is open source](https://github.com/heroku/buildpacks-procfile). The `heroku/procfile` buildpack allows you to configure your web startup process.
+
+This is the `Procfile` of the getting started guide:
+
+```
+:::-> $ cat Procfile
+```
+
+By including this file and using `heroku/procfile` buildpack, your application will receive a default web process. You can configure this behavior by changing the contents of that file.

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

@@ -0,0 +1,52 @@
+## Use the image
+
+Even though we used `pack` and CNBs to build our image, it can be run with your favorite tools like any other OCI image. We will be using the `docker` command line to run our image.
+
+By default, images will be booted into a web server configuration. You can launch the app we just built by running:
+
+```
+$ docker run -it --rm --env PORT=9292 -p 9292:9292 my-image-name
+:::-> background.start("docker run --rm --env PORT=9292 -p 9292:9292 my-image-name", name: "docker_server")
+:::-- $ sleep 10
+:::-> background.log.read(name: "docker_server")
+```
+
+Now when you visit [http://localhost:9292](http://localhost:9292) you should see a working web application:
+
+```
+:::>> website.visit(name: "localhost", url: "http://localhost:9292")
+:::>> website.screenshot(name: "localhost")
+```
+
+Don't forget to stop the docker container when you're done.
+
+```
+:::-- $ docker stop $(docker ps -q --filter ancestor=my-image-name )
+:::-- background.stop(name: "docker_server")
+```
+
+Here's a quick breakdown of that command we just ran:
+
+- `docker run` Create and run a new container from an image.
+- `-it` Makes the container interactive and allocates a TTY.
+- `--rm` Automatically remove the container when it exits.
+- `--env PORT=9292` Creates an environment variable named `PORT` and sets it to `9292` this is needed so the application inside the container knows what port to bind the web server.
+- `-p 9292:9292` Publishes a container's port(s) to the host. This is what allows requests from your machine to be received by the container.
+- `my-image-name` The name of the image you want to use for the application.
+
+So far, we've downloaded an application via git and run a single command `pack build` to generate an image, and then we can use that image as if it was generated via a Dockerfile via the `docker run` command.
+
+In addition to running the image as a web server, you can access the container's terminal interactively. In a new terminal window try running this command:
+
+```
+$ docker run -it --rm my-image-name bash
+```
+
+Now you can inspect the container interactively. For example, you can see the files on disk with `ls`:
+
+```
+$ ls
+:::-> $ docker run --rm my-image-name ls
+```
+
+And anything else you would typically do via an interactive container session.

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

@@ -0,0 +1,18 @@
+## What is a builder?
+
+> [!NOTE]
+> Skip ahead if you want to build the application first and get into the details later. You won't need to
+> know about builders for the rest of this tutorial.
+
+In short, a builder is a delivery mechanism for buildpacks. A builder contains references to base images and individual buildpacks. A base image contains the operating system and system dependencies. Buildpacks are the components that will configure an image to run your application, that’s where the bulk of the logic lives and why the project is called “Cloud Native Buildpacks” and not “Cloud Native Builders.”
+
+You can view the contents of a builder via the command `pack builder inspect`. For example:
+
+```
+:::>> $ pack builder inspect heroku/builder:22 | grep Buildpacks: -m1 -A10
+```
+
+> [!NOTE]
+> Your output version numbers may differ.
+
+This output shows the various buildpacks that represent the different languages that are supported by this builder such as `heroku/go` and `heroku/nodejs-engine`.

data/test/fixtures/rails_7/rundoc.md

@@ -3,7 +3,6 @@
 email = ENV['HEROKU_EMAIL'] || `heroku auth:whoami`
 
 Rundoc.configure do |config|
-  config.project_root = "myapp"
   config.filter_sensitive(email => "developer@example.com")
   config.filter_sensitive(Dir.pwd => ".")
 end

data/test/fixtures/simple_git/rundoc.md

@@ -0,0 +1,13 @@
+```
+:::-- $ git config --get user.email || git config --global user.email "developer@example.com"
+:::-- $ git config --get user.name || git config --global user.name "Developer name"
+```
+
+```
+:::>> $ echo "hello world" >> lol.txt
+:::>> $ git init .
+:::>> $ git add .
+:::>> $ git commit -m first
+:::>> $ echo "so long and thanks for all the fish" >> lol.txt
+:::>> $ git add . && git commit -m second
+```

data/test/integration/after_build_test.rb

@@ -0,0 +1,62 @@
+require "test_helper"
+
+class IntegrationAfterBuildTest < Minitest::Test
+  def test_modifies_directory_structure
+    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
+          ```
+        EOF
+
+        io = StringIO.new
+
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert dir.join(SUCCESS_DIRNAME).join("lol").exist?
+        assert dir.join(SUCCESS_DIRNAME).join("lol").join("rofl.txt").exist?
+
+        FileUtils.remove_entry_secure(dir.join(SUCCESS_DIRNAME))
+
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.configure
+          Rundoc.configure do |config|
+            config.after_build do |context|
+              Dir.glob(context.output_dir.join("lol").join("*")).each do |item|
+                FileUtils.mv(item, context.output_dir)
+              end
+
+              FileUtils.rm_rf(context.output_dir.join("lol"))
+            end
+          end
+          ```
+
+          ```
+          :::>> $ mkdir lol
+          :::>> $ touch lol/rofl.txt
+          ```
+        EOF
+
+        io = StringIO.new
+
+        Rundoc::CLI.new(
+          io: io,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert dir.join(SUCCESS_DIRNAME).join("rofl.txt").exist?
+      end
+    end
+  end
+end

data/test/integration/print_test.rb

@@ -1,6 +1,6 @@
 require "test_helper"
 
-class ParserTest < Minitest::Test
+class IntegrationPrintTest < Minitest::Test
   def test_erb_shared_binding_persists_values
     key = SecureRandom.hex
     contents = <<~RUBY
@@ -20,7 +20,7 @@ class ParserTest < Minitest::Test
           one
           #{key}
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -43,7 +43,7 @@ class ParserTest < Minitest::Test
         expected = <<~EOF
           one
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -69,7 +69,7 @@ class ParserTest < Minitest::Test
           there
           ```
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -93,7 +93,7 @@ class ParserTest < Minitest::Test
           Hello
           there
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -117,7 +117,7 @@ class ParserTest < Minitest::Test
           Hello
           there
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -141,7 +141,7 @@ class ParserTest < Minitest::Test
           Hello
           there
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -162,7 +162,7 @@ class ParserTest < Minitest::Test
         expected = <<~EOF
           Hello there
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -185,7 +185,7 @@ class ParserTest < Minitest::Test
           Hello there
           ```
         EOF
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end

data/test/integration/require_test.rb

@@ -0,0 +1,63 @@
+require "test_helper"
+
+class IntegrationRequireTest < Minitest::Test
+  def test_require_embeds_results
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> rundoc.require "./day_one/rundoc.md"
+          ```
+        EOF
+
+        dir.join("day_one").tap(&:mkpath).join("rundoc.md").write <<~EOF
+          ```
+          :::-> print.text Hello World!
+          ```
+        EOF
+
+        parsed = parse_contents(
+          source_path.read,
+          source_path: source_path
+        )
+        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        assert_equal "Hello World!", actual.strip
+      end
+    end
+  end
+
+  def test_require_runs_code_but_embeds_nothing_if_hidden
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.require "./day_one/rundoc.md"
+          ```
+        EOF
+
+        dir.join("day_one").tap(&:mkpath).join("rundoc.md").write <<~EOF
+          ```
+          :::-> print.text Hello World!
+          :::>> $ echo "echo hello world" > foo.txt
+          ```
+        EOF
+
+        parsed = parse_contents(
+          source_path.read,
+          source_path: source_path
+        )
+        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+        # Command was run
+        assert dir.join("foo.txt").exist?
+        assert "echo hello world", dir.join("foo.txt").read.strip
+
+        # But nothing was embedded
+        assert_equal "", actual.strip
+      end
+    end
+  end
+end

data/test/integration/website_test.rb

@@ -0,0 +1,35 @@
+require "test_helper"
+
+class IntegrationWebsiteTest < Minitest::Test
+  def test_screenshot_command
+    contents = <<~RUBY
+      ```
+      :::>> website.visit(name: "example", url: "http://example.com")
+      :::>> website.screenshot(name: "example")
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        env = {}
+        env[:before] = []
+
+        screenshots_dirname = "screenshots"
+        screenshots_dir = Pathname(dir).join(screenshots_dirname)
+        screenshot_1_path = screenshots_dir.join("screenshot_1.png")
+
+        parsed = parse_contents(
+          contents,
+          output_dir: screenshots_dir.parent,
+          screenshots_dirname: screenshots_dirname
+        )
+        actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
+
+        expected = "![Screenshot of http://example.com/](screenshots/screenshot_1.png)"
+        assert_equal expected, actual.strip
+
+        assert screenshot_1_path.exist?
+      end
+    end
+  end
+end

data/test/rundoc/cli_argument_parser_test.rb

@@ -0,0 +1,118 @@
+require "test_helper"
+
+class CliArgumentParserTest < Minitest::Test
+  def test_help
+    io = StringIO.new
+    exit_obj = FakeExit.new
+    parser = Rundoc::CLIArgumentParser.new(
+      io: io,
+      argv: ["--help"],
+      env: {},
+      exit_obj: exit_obj
+    )
+    parser.call
+    output = io.string
+
+    assert output.include?("Prints this help output")
+  end
+
+  def test_help_no_flag
+    io = StringIO.new
+    exit_obj = FakeExit.new
+    parser = Rundoc::CLIArgumentParser.new(
+      io: io,
+      argv: ["help"],
+      env: {},
+      exit_obj: exit_obj
+    )
+    parser.call
+    output = io.string
+
+    assert output.include?("Prints this help output")
+  end
+
+  def test_no_such_file
+    io = StringIO.new
+    exit_obj = FakeExit.new
+    parser = Rundoc::CLIArgumentParser.new(
+      io: io,
+      argv: ["fileDoesNotExist.txt"],
+      env: {},
+      exit_obj: exit_obj
+    )
+    parser.call
+    output = io.string
+
+    assert exit_obj.value == 1
+    assert_includes output, "No such file"
+  end
+
+  def test_dir_not_file
+    Dir.mktmpdir do |dir|
+      io = StringIO.new
+      exit_obj = FakeExit.new
+      parser = Rundoc::CLIArgumentParser.new(
+        io: io,
+        argv: [dir],
+        env: {},
+        exit_obj: exit_obj
+      )
+      parser.call
+      output = io.string
+
+      assert exit_obj.value == 1
+      assert_includes output, "Path is not a file"
+    end
+  end
+
+  def test_valid_inputs
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        tmp = Pathname(dir)
+        rundoc = tmp.join("rundoc.md")
+        rundoc.write("")
+
+        io = StringIO.new
+        exit_obj = FakeExit.new
+        parser = Rundoc::CLIArgumentParser.new(
+          io: io,
+          argv: [
+            rundoc,
+            "--on-success-dir=./success",
+            "--on-failure-dir=./failure",
+            "--dotenv-path=./lol/.env",
+            "--screenshots-dirname=pics",
+            "--output-filename=OUTPUT.md",
+            "--force"
+          ],
+          env: {},
+          exit_obj: exit_obj
+        )
+        parser.call
+        output = io.string
+
+        assert !exit_obj.called?
+        assert output.empty?
+
+        assert_equal "./success", parser.options[:on_success_dir]
+        assert_equal "./failure", parser.options[:on_failure_dir]
+        assert_equal "./lol/.env", parser.options[:dotenv_path]
+        assert_equal "pics", parser.options[:screenshots_dirname]
+        assert_equal "OUTPUT.md", parser.options[:output_filename]
+        assert_equal true, parser.options[:force]
+
+        expected = [
+          :on_success_dir,
+          :on_failure_dir,
+          :dotenv_path,
+          :screenshots_dirname,
+          :output_filename,
+          :force,
+          :io,
+          :source_path
+        ]
+        assert_equal expected.sort, parser.options.keys.sort
+      end
+    end
+  end
+end

data/test/rundoc/code_section_test.rb

@@ -15,7 +15,11 @@ class CodeSectionTest < Minitest::Test
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-        result = Rundoc::CodeSection.new(match, keyword: ":::").render
+        result = Rundoc::CodeSection.new(
+          match,
+          keyword: ":::",
+          context: default_context
+        ).render
         assert_equal "", result
       end
     end
@@ -30,7 +34,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    result = Rundoc::CodeSection.new(match, keyword: ":::").render
+    result = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    ).render
     assert_equal contents, result.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "\n")
   end
 
@@ -42,7 +50,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(match, keyword: ":::")
+    code_section = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    )
     code_section.render
 
     code_command = code_section.commands.first
@@ -56,7 +68,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(match, keyword: ":::")
+    code_section = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    )
     code_section.render
 
     code_command = code_section.commands.first
@@ -72,7 +88,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(match, keyword: ":::")
+    code_section = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    )
     code_section.render
 
     puts code_section.commands.inspect
@@ -89,7 +109,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(match, keyword: ":::")
+    code_section = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    )
     code_section.render
 
     code_command = code_section.commands.first
@@ -103,7 +127,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(match, keyword: ":::")
+    code_section = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    )
     code_section.render
 
     code_command = code_section.commands.first
@@ -119,7 +147,11 @@ class CodeSectionTest < Minitest::Test
     RUBY
 
     match = contents.match(Rundoc::Parser::CODEBLOCK_REGEX)
-    code_section = Rundoc::CodeSection.new(match, keyword: ":::")
+    code_section = Rundoc::CodeSection.new(
+      match,
+      keyword: ":::",
+      context: default_context
+    )
     code_section.render
 
     code_command = code_section.commands.first

data/test/rundoc/parser_test.rb

@@ -16,7 +16,7 @@ class ParserTest < Minitest::Test
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         expected = "sup\n\n```\n$ mkdir foo\n$ ls\nfoo\n```\n\nyo\n"
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -38,7 +38,7 @@ class ParserTest < Minitest::Test
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         expected = "sup\n\nIn file `foo/code.rb` write:\n\n```\na = 1 + 1\nb = a * 2\n```\nyo\n"
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end
@@ -56,7 +56,7 @@ class ParserTest < Minitest::Test
     Dir.mktmpdir do |dir|
       Dir.chdir(dir) do
         expected = "\nIn file `foo/newb.rb` write:\n\n```\nputs 'hello world'\n$ cat foo/newb.rb\nputs 'hello world'\n```\n"
-        parsed = Rundoc::Parser.new(contents)
+        parsed = parse_contents(contents)
         actual = parsed.to_md.gsub(Rundoc::CodeSection::AUTOGEN_WARNING, "")
         assert_equal expected, actual
       end

data/test/rundoc/peg_parser_test.rb

@@ -270,36 +270,36 @@ class PegParserTest < Minitest::Test
 
   def test_rundoc_sub_commands_no_quotes
     input = +""
-    input << %(:::-- rundoc.depend_on ../foo/bar.md\n)
+    input << %(:::-- rundoc.require ../foo/bar.md\n)
 
     parser = Rundoc::PegParser.new.command_with_stdin
     tree = parser.parse_with_debug(input)
 
     actual = @transformer.apply(tree)
-    assert_equal :"rundoc.depend_on", actual.keyword
+    assert_equal :"rundoc.require", actual.keyword
   end
 
   def test_seattle_style_method_call
     input = +""
-    input << %(rundoc.depend_on '../foo/bar.md')
+    input << %(rundoc.require '../foo/bar.md')
     parser = Rundoc::PegParser.new.method_call
     tree = parser.parse_with_debug(input)
 
     actual = @transformer.apply(tree)
 
-    assert_equal :"rundoc.depend_on", actual.keyword
+    assert_equal :"rundoc.require", actual.keyword
   end
 
   def test_rundoc_seattle_sub_command
     input = +""
-    input << %(:::>> rundoc.depend_on '../foo/bar.md'\n)
+    input << %(:::>> rundoc.require '../foo/bar.md'\n)
 
     parser = Rundoc::PegParser.new.command
     tree = parser.parse_with_debug(input)
 
     actual = @transformer.apply(tree)
 
-    assert_equal :"rundoc.depend_on", actual.keyword
+    assert_equal :"rundoc.require", actual.keyword
   end
 
   def test_positional_args