rfd-processor: Add PDF test; pin ruby/js dependencies explicitly

.gitattributes

@@ -0,0 +1 @@
+*.pdf binary

.github/workflows/test.yml

@@ -10,6 +10,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref_name }}-${{ github.ref_name == 'main' && github.sha || 'anysha' }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-24.04
@@ -29,19 +32,23 @@ jobs:
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Install asciidoctor
-        shell: bash
-        run: |
-          sudo apt update -y && sudo apt install -y \
-            asciidoctor \
-            ruby \
-      - name: Install asciidoctor-pdf, asciidoctor-mermaid
+      - uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.3.7
+        with:
+          working-directory: rfd-processor
+          bundler-cache: true
+      - name: Install PDF toolchain
         shell: bash
+        working-directory: rfd-processor
         run: |
-          sudo gem install rouge
-          sudo gem install asciidoctor-pdf -v 2.3.2
-          sudo gem install asciidoctor-mermaid -v 0.4.1
-          sudo npm install -g @mermaid-js/mermaid-cli@11.4.0
+          bundle config set bin .bundle/bin
+          bundle binstubs asciidoctor asciidoctor-pdf
+          npm ci
+          printf '%s\n' '{"args":["--no-sandbox"]}' > .bundle/bin/puppeteer.json
+          printf '%s\n' '#!/usr/bin/env bash' \
+            "exec '$PWD/node_modules/.bin/mmdc' --puppeteerConfigFile '$PWD/.bundle/bin/puppeteer.json' \"\$@\"" \
+            > .bundle/bin/mmdc
+          chmod +x .bundle/bin/mmdc
+          echo "$PWD/.bundle/bin" >> "$GITHUB_PATH"
       - name: Report versions
         run: |
           asciidoctor --version
@@ -55,6 +62,34 @@ jobs:
         env:
           TEST_DATABASE: postgres://test:test@localhost
           RUST_LOG: v=trace,rfd=trace
+      - name: Verify RFD 9999 PDF fixture
+        shell: bash
+        run: |
+          expected_pdf="rfd-processor/tests/rfd_9999.pdf"
+          generated_pdf="rfd-processor/tests/rfd_9999-generated.pdf"
+          diff_pdf="rfd-processor/tests/rfd_9999-diff.pdf"
+
+          cargo run --profile test -p rfd-processor -- pdf rfd-processor/tests/rfd_9999 -o "$generated_pdf"
+
+          expected_checksum="$(sha256sum "$expected_pdf" | cut -d ' ' -f 1)"
+          generated_checksum="$(sha256sum "$generated_pdf" | cut -d ' ' -f 1)"
+
+          if [[ "$expected_checksum" != "$generated_checksum" ]]; then
+            echo "Rendered PDF does not match checked-in RFD 9999 PDF"
+            sudo apt-get update
+            sudo apt-get install -y diff-pdf-wx xvfb
+            xvfb-run -a diff-pdf --skip-identical --mark-differences "$diff_pdf" "$expected_pdf" --output-diff "$generated_pdf" || true
+            exit 1
+          fi
+      - name: Upload rendered PDF
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: rfd-processor-rfd-9999-pdf-artifacts
+          path: |
+            rfd-processor/tests/rfd_9999-generated.pdf
+            rfd-processor/tests/rfd_9999-diff.pdf
+          if-no-files-found: ignore
 
   generate:
     runs-on: ubuntu-24.04

.gitignore

@@ -2,6 +2,8 @@
 
 node_modules
 dist
+**/.bundle
+**/vendor/bundle
 
 config.toml
 mappers.toml

README.md

@@ -43,13 +43,51 @@ Running the API requires setting up a configuration file as outlined in `config.
 
 Dependencies
 
-* asciidoctor
-* Node
-  * @mermaid-js/mermaid-cli
-* Ruby
-  * rouge
-  * asciidoctor-pdf
-  * asciidoctor-mermaid
+The PDF renderer shells out to `asciidoctor-pdf` and `mmdc`. The toolchain
+versions are pinned in: `rfd-processor/Gemfile` and `rfd-processor/package.json`.
+
+Install the Ruby dependencies:
+
+```sh
+cd rfd-processor
+gem install bundler -v 4.0.11
+bundle config set path vendor/bundle
+bundle config set bin .bundle/bin
+bundle install
+bundle binstubs asciidoctor asciidoctor-pdf
+export PATH="$PWD/.bundle/bin:$PATH"
+```
+
+Install the Node dependencies and Chromium runtime used by Mermaid:
+
+```sh
+cd rfd-processor
+npm ci
+export PATH="$PWD/node_modules/.bin:$PATH"
+```
+
+On macOS, use `brew install ruby@3.2` and then install the PDF toolchain
+through Bundler and npm as shown above.
+If you previously installed `asciidoctor` via Homebrew, uninstall
+with `brew uninstall asciidoctor`.
+
+Render an RFD directory with:
+
+```sh
+PATH="$PWD/rfd-processor/.bundle/bin:$PWD/rfd-processor/node_modules/.bin:$PATH" \
+    cargo run -p rfd-processor -- pdf rfd-processor/tests/rfd_9999 -o /tmp/rfd_9999.pdf
+```
+
+On macOS with Homebrew Ruby:
+
+```sh
+PATH="/opt/homebrew/opt/ruby@3.2/bin:$PWD/rfd-processor/.bundle/bin:$PWD/rfd-processor/node_modules/.bin:$PATH" \
+    cargo run -p rfd-processor -- pdf rfd-processor/tests/rfd_9999 -o /tmp/rfd_9999.pdf
+```
+
+CI renders `rfd-processor/tests/rfd_9999` on Linux and compares the checksum
+against `rfd-processor/tests/rfd_9999.pdf`. If the checksum changes, CI uploads
+the generated PDF and a `diff-pdf` visual diff artifact.
 
 ## Background
 

rfd-processor/.ruby-version

@@ -0,0 +1 @@
+3.2.3

rfd-processor/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gem "asciidoctor", "2.0.20"
+gem "asciidoctor-mermaid", "0.4.1"
+gem "asciidoctor-pdf", "2.3.2"
+gem "base64", "0.3.0"
+gem "logger", "1.7.0"
+gem "rouge", "4.5.1"

rfd-processor/Gemfile.lock

@@ -0,0 +1,99 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (2.0.1)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    afm (1.0.0)
+    asciidoctor (2.0.20)
+    asciidoctor-mermaid (0.4.1)
+    asciidoctor-pdf (2.3.2)
+      asciidoctor (~> 2.0)
+      concurrent-ruby (~> 1.1)
+      matrix (~> 0.4)
+      prawn (~> 2.4.0)
+      prawn-icon (~> 3.0.0)
+      prawn-svg (~> 0.32.0)
+      prawn-table (~> 0.2.0)
+      prawn-templates (~> 0.1.0)
+      treetop (~> 1.6.0)
+    base64 (0.3.0)
+    concurrent-ruby (1.3.7)
+    css_parser (1.22.0)
+      addressable
+    hashery (2.1.2)
+    logger (1.7.0)
+    matrix (0.4.3)
+    pdf-core (0.9.0)
+    pdf-reader (2.15.1)
+      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
+      afm (>= 0.2.1, < 2)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    polyglot (0.3.5)
+    prawn (2.4.0)
+      pdf-core (~> 0.9.0)
+      ttfunk (~> 1.7)
+    prawn-icon (3.0.0)
+      prawn (>= 1.1.0, < 3.0.0)
+    prawn-svg (0.32.0)
+      css_parser (~> 1.6)
+      prawn (>= 0.11.1, < 3)
+      rexml (~> 3.2)
+    prawn-table (0.2.2)
+      prawn (>= 1.3.0, < 3.0.0)
+    prawn-templates (0.1.2)
+      pdf-reader (~> 2.0)
+      prawn (~> 2.2)
+    public_suffix (7.0.5)
+    rexml (3.4.4)
+    rouge (4.5.1)
+    ruby-rc4 (0.1.5)
+    treetop (1.6.18)
+      polyglot (~> 0.3)
+    ttfunk (1.7.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  asciidoctor (= 2.0.20)
+  asciidoctor-mermaid (= 0.4.1)
+  asciidoctor-pdf (= 2.3.2)
+  base64 (= 0.3.0)
+  logger (= 1.7.0)
+  rouge (= 4.5.1)
+
+CHECKSUMS
+  Ascii85 (2.0.1) sha256=15cb5d941808543cbb9e7e6aea3c8ec3877f154c3461e8b3673e97f7ecedbe5a
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  afm (1.0.0) sha256=5bd4d6f6241e7014ef090985ec6f4c3e9745f6de0828ddd58bc1efdd138f4545
+  asciidoctor (2.0.20) sha256=835eabd445e4ae88f56a5f4e07593c3612b2be72eb661c612c3a8e1e17c57479
+  asciidoctor-mermaid (0.4.1) sha256=51146b0df171d112c118df9236c062f38a5da49afd2086baf21a3ab95343a46c
+  asciidoctor-pdf (2.3.2) sha256=bb83308a68ede1c00a12b9110f9255f09e75361bd74e218be584f49c6905bc9a
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bundler (4.0.11) sha256=5bcec0fb78302e48d02ee46f10ee6e6942be647ba5b44a6d1ddfda9a240ce785
+  concurrent-ruby (1.3.7) sha256=4412caec3a5ea2e5fdc52076724c071a81f2c0593d83b2ac8cbb8ca63b3151b0
+  css_parser (1.22.0) sha256=f274988a40c6178305530d60e7deb5162f7b5538b701b61b5488fc703e5b40c1
+  hashery (2.1.2) sha256=d239cc2310401903f6b79d458c2bbef5bf74c46f3f974ae9c1061fb74a404862
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  matrix (0.4.3) sha256=a0d5ab7ddcc1973ff690ab361b67f359acbb16958d1dc072b8b956a286564c5b
+  pdf-core (0.9.0) sha256=4f368b2f12b57ec979872d4bf4bd1a67e8648e0c81ab89801431d2fc89f4e0bb
+  pdf-reader (2.15.1) sha256=18c6a986a84a3117fa49f4279fc2de51f5d2399b71833df5d2bccd595c7068ce
+  polyglot (0.3.5) sha256=59d66ef5e3c166431c39cb8b7c1d02af419051352f27912f6a43981b3def16af
+  prawn (2.4.0) sha256=82062744f7126c2d77501da253a154271790254dfa8c309b8e52e79bc5de2abd
+  prawn-icon (3.0.0) sha256=dac8d481dee0f60a769c0cab0fd1baec7351b4806bf9ba959cd6c65f6694b6f5
+  prawn-svg (0.32.0) sha256=66d1a20a93282528a25d5ad9e0db422dad4804a34e0892561b64c3930fff7d55
+  prawn-table (0.2.2) sha256=336d46e39e003f77bf973337a958af6a68300b941c85cb22288872dc2b36addb
+  prawn-templates (0.1.2) sha256=117aa03db570147cb86fcd7de4fd896994f702eada1d699848a9529a87cd31f1
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rouge (4.5.1) sha256=2ac81c6dee7019bbc6600d4c2d641d730d65c165941400ebd924259067e690dd
+  ruby-rc4 (0.1.5) sha256=00cc40a39d20b53f5459e7ea006a92cf584e9bc275e2a6f7aa1515510e896c03
+  treetop (1.6.18) sha256=a3043f32f1c652aa2abdf3a3848edb2d2f69897257af2675516ac61355c183da
+  ttfunk (1.7.0) sha256=2370ba484b1891c70bdcafd3448cfd82a32dd794802d81d720a64c15d3ef2a96
+
+BUNDLED WITH
+  4.0.11