probatio_diabolica 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c53898870646f0712544d5bc8998715622cffb4981711737757c26d3f8e41ad7
-  data.tar.gz: e3a828ea56faac76e54443c1292235a849bbfd0aca1ff9745c94b3f53190650e
+  metadata.gz: 368faf074dc354becfef975422fc3199a1e83293a30bad935ef17696a9b879c9
+  data.tar.gz: 66b84421f306926f425cdc6d9e5cc4a1ff3b8ed1cd4f6df13e86bd7313796c5d
 SHA512:
-  metadata.gz: 38aa1da254d62abeed89a013e82a1e87b63970c4faedf0fb858d140e3a83a8c61a2fc16fff6f073e0cafd81260f762a7fa0ab294d7a879f20c27c204d9549d50
-  data.tar.gz: 5e108178e7da9d4ec7605959f96c6b782754a068bcec05faedac09bf93c709fc559cf1c4fb6e0f71aaa6110f396ec2a2f549092ab1f17581efd7d8a92a5dd8d9
+  metadata.gz: f9cce79af416cc2b0e216820dd3f07f2d0ba46552db2e2598d9ab2ab83f1492757044717a383256db7b6d14168a3da4d11a0cf89949f6ec1eebe4bf55f366f2c
+  data.tar.gz: 03e7a8a23b02b473e8bac35c4b4021e729b4e435408bdc69a6143162eebdad8172ec5bb07b83d4471b87464c5f42b1346a112d0e1d7f3af061f916838ea13ea8

data/README.md

@@ -56,6 +56,28 @@ gem build probatio_diabolica.gemspec
 gem install ./probatio_diabolica-*.gem
 ```
 
+## Release workflow
+
+Use the release helper to bump version, refresh `Gemfile.lock`, create commit/tag, and push:
+
+```bash
+# explicit version
+bin/release --version 0.2.0
+
+# or env-style
+VERSION=0.2.0 bin/release
+
+# semantic bump from current version
+bin/release --bump patch
+```
+
+Useful options:
+
+- `--dry-run` preview all actions without modifying files/git
+- `--no-push` create commit/tag locally only
+- `--skip-tests` skip `bundle exec ruby bin/prd spec --mode synthetic`
+- `--allow-dirty` bypass clean-working-tree guard
+
 After installation, you can run:
 
 ```bash
@@ -85,39 +107,63 @@ Without valid configuration, tests using `satisfy(...)` will fail.
 
 ## Running tests
 
-Command:
+CLI command:
 
 ```bash
 prd <file_or_directory> [options]
 ```
 
-From source checkout (without gem install), use:
+From source checkout (without gem install), this is always valid:
 
 ```bash
-bundle exec prd <file_or_directory> [options]
+bundle exec ruby bin/prd <file_or_directory> [options]
 ```
 
-Supported options:
+Options:
 
-- `-o, --out DIR` writes output to `DIR/report.qd` (otherwise stdout)
 - `-c, --config FILE` Ruby config file to require
-- `-t, --type TYPE` formatter type (`simple` by default; supports `simple`, `html`, `json`, `pdf`)
-- `-m, --mode MODE` output verbosity mode (`verbose` by default; supports `verbose`, `synthetic`)
+- `-t, --type TYPE` formatter type(s), default: `simple`
+  - supported: `simple`, `html`, `json`, `pdf`
+  - can be repeated (`-t html -t json`) or comma-separated (`-t html,json,pdf`)
+- `-o, --out PATH` output base path (directory or file-like base name)
+- `-m, --mode MODE` output mode, default: `verbose`
+  - supported: `verbose`, `synthetic`
+
+Output rules (`--out`):
+
+- No `--out`:
+  - one formatter (`simple`, `html`, or `json`): output goes to `stdout`
+  - `pdf`: fails (`PDF formatter requires --out`)
+  - multiple formatters: fails (`Multiple formatter types require --out`)
+- With `--out PATH`:
+  - if `PATH` exists as a directory, or ends with `/`, reports are written as `PATH/report.<ext>`
+  - otherwise, `PATH` is treated as a base name and reports are written as `PATH.<ext>`
+  - if `PATH` ends with one known extension (`.txt`, `.html`, `.json`, `.pdf`), that extension is stripped before generating outputs
+
+Formatter/file extension mapping:
+
+- `simple` -> `.txt`
+- `html` -> `.html`
+- `json` -> `.json`
+- `pdf` -> `.pdf`
 
 Examples:
 
 ```bash
 # single file
-bundle exec prd examples/basics_spec.rb
+bundle exec ruby bin/prd examples/basics_spec.rb
 
 # all *_spec.rb files in a directory
-bundle exec prd examples
+bundle exec ruby bin/prd examples
 
-# HTML report
-bundle exec prd examples/image_spec.rb -t html -o ./tmp
+# HTML report in an existing directory (creates ./tmp/report.html)
+bundle exec ruby bin/prd examples/image_spec.rb -t html -o ./tmp/
+
+# multiple reports from one run with shared base name
+bundle exec ruby bin/prd examples/basics_spec.rb -t html,json,pdf -o ./tmp/my_report
 
 # compact synthetic output on console
-bundle exec prd examples/basics_spec.rb --mode synthetic
+bundle exec ruby bin/prd examples/basics_spec.rb --mode synthetic
 ```
 
 ## Available DSL
@@ -210,7 +256,13 @@ The runtime keeps a model stack (`it` can temporarily override the parent `conte
 
 - `PrD::Formatters::SimpleFormatter` (text console output)
 - `PrD::Formatters::HtmlFormatter` (simple HTML output)
-- `PrD::Formatters::JsonFormatter` exists in code but is not currently exposed by `bin/prd`
+- `PrD::Formatters::JsonFormatter` (structured JSON output)
+- `PrD::Formatters::PdfFormatter` (PDF report output)
+
+In CLI usage:
+
+- selecting one formatter writes one output stream/file
+- selecting multiple formatters runs tests once and writes one file per formatter
 
 ### Subject rendering policy (best effort)
 
@@ -245,5 +297,5 @@ The goal is to preserve readability and report size while surfacing the richest
 ## Current limitations
 
 - Work in progress, API may change.
-- Strong dependency on an LLM provider for `satisfy`.
-- `-o` output is always written to a file named `report.qd`.
+- `satisfy(...)` requires a configured LLM provider and network access.
+- PDF and multi-format output require `--out`.

data/bin/prd

@@ -6,15 +6,93 @@ rescue LoadError
   require_relative '../lib/pr_d'
 end
 require 'optparse'
+require 'fileutils'
 
-options = {}
+FORMATTERS = {
+  'simple' => { klass: PrD::Formatters::SimpleFormatter, extension: '.txt', binary: false },
+  'html' => { klass: PrD::Formatters::HtmlFormatter, extension: '.html', binary: false },
+  'json' => { klass: PrD::Formatters::JsonFormatter, extension: '.json', binary: false },
+  'pdf' => { klass: PrD::Formatters::PdfFormatter, extension: '.pdf', binary: true }
+}.freeze
+
+SUPPORTED_FORMATTERS = FORMATTERS.keys.freeze
+SUPPORTED_MODES = %w[verbose synthetic].freeze
+DEFAULT_REPORT_BASENAME = 'report'.freeze
+
+class CompositeFormatter
+  def initialize(formatters)
+    @formatters = formatters
+  end
+
+  def method_missing(name, *args, &block)
+    handled = false
+    @formatters.each do |formatter|
+      next unless formatter.respond_to?(name)
+
+      formatter.public_send(name, *args, &block)
+      handled = true
+    end
+
+    return if handled
+
+    super
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    @formatters.any? { |formatter| formatter.respond_to?(name, include_private) } || super
+  end
+end
+
+def parse_formatter_types(raw_values)
+  types = Array(raw_values)
+            .flat_map { |value| value.to_s.split(',') }
+            .map(&:strip)
+            .reject(&:empty?)
+  types = ['simple'] if types.empty?
+
+  unknown_types = types - SUPPORTED_FORMATTERS
+  unless unknown_types.empty?
+    supported = SUPPORTED_FORMATTERS.join(', ')
+    raise "Unsupported formatter type: #{unknown_types.first}. Supported: #{supported}"
+  end
+
+  types.uniq
+end
+
+def normalize_mode(raw_mode)
+  mode = raw_mode || 'verbose'
+  supported = SUPPORTED_MODES.join(', ')
+  raise "Unsupported mode: #{mode}. Supported: #{supported}" unless SUPPORTED_MODES.include?(mode)
+
+  mode
+end
+
+def directory_like_path?(path)
+  path.end_with?(File::SEPARATOR) || Dir.exist?(path)
+end
+
+def output_base_path(out_path)
+  return nil if out_path.nil?
+
+  if directory_like_path?(out_path)
+    File.join(out_path, DEFAULT_REPORT_BASENAME)
+  else
+    known_extensions = FORMATTERS.values.map { |config| config[:extension].downcase }
+    ext = File.extname(out_path).downcase
+    return out_path[...-ext.length] if known_extensions.include?(ext)
+
+    out_path
+  end
+end
+
+options = { formatters: [] }
 OptionParser
   .new do |opts|
     opts.banner = 'Usage: prd [options] FILE_OR_DIR'
-    opts.on('-o', '--out DIR', 'Specify the output directory') { |dir| options[:out] = dir }
+    opts.on('-o', '--out PATH', 'Specify output base path (directory or path/name)') { |path| options[:out] = path }
     opts.on('-c', '--config FILE', 'Specify the config file') { |file| options[:config] = file }
-    opts.on('-t', '--type TYPE', 'Specify the formatter type (simple, html, json, pdf)') do |type|
-      options[:formatter] = type
+    opts.on('-t', '--type TYPE', 'Specify formatter type(s): simple, html, json, pdf (repeat or comma-separated)') do |type|
+      options[:formatters] << type
     end
     opts.on('-m', '--mode MODE', 'Specify output mode (verbose, synthetic)') do |mode|
       options[:mode] = mode
@@ -36,47 +114,50 @@ tests =
     [File.read(input_path)]
   end
 
-io =
-  if options[:out].nil?
-    raise 'PDF formatter requires --out to write a binary report file.' if options[:formatter] == 'pdf'
-    STDOUT
-  else
-    Dir.mkdir(options[:out]) unless Dir.exist?(options[:out])
-    report_filename = case options[:formatter]
-                      when 'html'
-                        'report.html'
-                      when 'pdf'
-                        'report.pdf'
-                      else
-                        'report.qd'
-                      end
-    mode = options[:formatter] == 'pdf' ? 'wb' : 'w'
-    File.open(File.join(options[:out], report_filename), mode)
-  end
+formatter_types = parse_formatter_types(options[:formatters])
+mode = normalize_mode(options[:mode])
+out_base = output_base_path(options[:out])
 
-formatter_class = case options[:formatter]
-                  when nil, 'simple'
-                    PrD::Formatters::SimpleFormatter
-                  when 'html'
-                    PrD::Formatters::HtmlFormatter
-                  when 'json'
-                    PrD::Formatters::JsonFormatter
-                  when 'pdf'
-                    PrD::Formatters::PdfFormatter
-                  else
-                    raise "Unsupported formatter type: #{options[:formatter]}. Supported: simple, html, json, pdf"
-                  end
-
-mode = options[:mode] || 'verbose'
-supported_modes = %w[verbose synthetic]
-raise "Unsupported mode: #{mode}. Supported: verbose, synthetic" unless supported_modes.include?(mode)
+if formatter_types.include?('pdf') && out_base.nil?
+  raise 'PDF formatter requires --out to write a binary report file.'
+end
+
+if formatter_types.length > 1 && out_base.nil?
+  raise 'Multiple formatter types require --out to specify where files will be written.'
+end
 
 serializers = {
   # Ferrum::Network::Exchange => (->(exchange) { exchange.url }),
   # PDF::Reader => (->(pdf) { pdf.pages.map(&:text).join("\n") })
 }
 
-formatter = formatter_class.new(io:, serializers:, mode: mode.to_sym)
-runtime = PrD::Runtime.new(formatter:, output_dir: options[:out], config_file: options[:config])
+destinations =
+  if out_base.nil?
+    [{ io: STDOUT, formatter: FORMATTERS.fetch(formatter_types.first)[:klass].new(io: STDOUT, serializers:, mode: mode.to_sym) }]
+  else
+    output_dir = File.dirname(out_base)
+    FileUtils.mkdir_p(output_dir)
+    formatter_types.map do |type|
+      config = FORMATTERS.fetch(type)
+      output_path = "#{out_base}#{config[:extension]}"
+      io = File.open(output_path, config[:binary] ? 'wb' : 'w')
+      { io:, formatter: config[:klass].new(io:, serializers:, mode: mode.to_sym) }
+    end
+  end
+
+formatter =
+  if destinations.length == 1
+    destinations.first[:formatter]
+  else
+    CompositeFormatter.new(destinations.map { |destination| destination[:formatter] })
+  end
+
+runtime_output_dir = out_base.nil? ? nil : File.dirname(out_base)
+runtime = PrD::Runtime.new(formatter:, output_dir: runtime_output_dir, config_file: options[:config])
 runtime.run(tests)
-io.close if io != STDOUT
+exit_status = runtime.success? ? 0 : 1
+destinations.each do |destination|
+  io = destination[:io]
+  io.close if io != STDOUT
+end
+exit(exit_status)

data/lib/pr_d/formatters/html_formatter.rb

@@ -6,14 +6,148 @@ module PrD
     class HtmlFormatter < Formatter
       def initialize(io: $stdout, serializers: {}, mode: :verbose)
         super(io: io, serializers: serializers, mode: mode)
-        @io << <<~HTML
+        @content = +''
+        @index_entries = []
+        @anchor_counters = Hash.new(0)
+      end
+
+      def context(message)
+        anchor_id = next_anchor_id('ctx')
+        add_index_entry(type: :context, label: message, level: @level, anchor_id:)
+        @content << "<h2 class=\"context\" id=\"#{anchor_id}\">#{escape(message)}</h2>"
+      end
+
+      def success_result(message)
+        if synthetic?
+          @content << "<div class='status success'>PASS</div>"
+          return
+        end
+        @content << "<div class='status success'>✓ #{escape(message)}</div>"
+      end
+
+      def failure_result(message)
+        if synthetic?
+          @content << "<div class='status failure'>FAIL</div>"
+          return
+        end
+        @content << "<div class='status failure'>✗ #{escape(message)}</div>"
+      end
+
+      def it(description = nil, &block)
+        @current_test_title = description.to_s
+        anchor_id = next_anchor_id('test')
+        add_index_entry(type: :test, label: description.to_s, level: @level, anchor_id:)
+        @content << "<article class=\"test-card\" id=\"#{anchor_id}\">"
+        @content << "<h3 class=\"test-title\">#{escape(description)}</h3>"
+      end
+
+      def end_it(description = nil, &block)
+        @content << '</article>'
+      end
+
+      def justification(justification)
+        return if synthetic?
+        @content << "<p class=\"line\"><strong>Justification:</strong> #{escape(justification)}</p>"
+      end
+
+      def let(value)
+      end
+
+      def subject(subject)
+        return if synthetic?
+        @content << '<div class="subject-block">'
+        @content << "<p class=\"line\"><strong>Subject:</strong> #{escape(serialize(subject).to_s)}</p>"
+        if image_file?(subject)
+          @content << "<img src=\"#{image_data_uri(subject.path)}\" alt=\"Subject image\" class=\"subject-image\" />"
+        elsif pdf_file?(subject)
+          @content << "<embed src=\"#{pdf_data_uri(subject.path)}\" type=\"application/pdf\" class=\"subject-pdf\" />"
+        elsif pdf_reader?(subject)
+          @content << "<embed src=\"#{pdf_reader_data_uri(subject)}\" type=\"application/pdf\" class=\"subject-pdf\" />"
+        end
+        @content << '</div>'
+      end
+
+      def pending(description = nil)
+        pending_label = description || 'Pending test'
+        anchor_id = next_anchor_id('pending')
+        add_index_entry(type: :pending, label: pending_label, level: @level, anchor_id:)
+
+        @content << "<article class=\"test-card\" id=\"#{anchor_id}\">"
+        @content << "<h3 class=\"test-title\">#{escape(pending_label)}</h3>"
+        if synthetic?
+          @content << "<div class='status pending'>PENDING</div>"
+        else
+          @content << "<div class='status pending'>⚠ #{escape(pending_label)}</div>"
+          @content << '<p class="line muted">This test is pending and has not been executed.</p>'
+        end
+        @content << '</article>'
+      end
+
+      def expect(expectation)
+        return if synthetic?
+        @content << "<p class=\"line\"><strong>Expect:</strong> #{escape(serialize(expectation).to_s)}</p>"
+      end
+
+      def to
+        return if synthetic?
+        @content << '<p class="line"><strong>To:</strong></p>'
+      end
+
+      def not_to
+        return if synthetic?
+        @content << '<p class="line"><strong>Not to:</strong></p>'
+      end
+
+      def matcher(matcher, sources: nil)
+        return if synthetic?
+        case matcher
+        when Matchers::EqMatcher
+          @content << "<p class=\"line\"><strong>Matcher:</strong> Be equal to #{escape(serialize(matcher.expected).to_s)}</p>"
+        when Matchers::BeMatcher
+          @content << "<p class=\"line\"><strong>Matcher:</strong> Be the same object as #{escape(serialize(matcher.expected).to_s)}</p>"
+        when Matchers::IncludesMatcher
+          @content << "<p class=\"line\"><strong>Matcher:</strong> Include #{escape(serialize(matcher.expected).to_s)}</p>"
+        when Matchers::HaveMatcher
+          @content << "<p class=\"line\"><strong>Matcher:</strong> Have #{escape(serialize(matcher.expected).to_s)}</p>"
+        when Matchers::LlmMatcher
+          @content << "<p class=\"line\"><strong>Matcher:</strong> Satisfy condition #{escape(serialize(matcher.expected).to_s)}</p>"
+        when Matchers::AllMatcher
+          if sources
+            code_line = matcher.expected.source_location.last.to_i
+            code = sources.lines[code_line - 1]
+            @content << "<p class=\"line\"><strong>Matcher:</strong> All match condition #{escape(code.strip)}</p>"
+          else
+            @content << '<p class="line"><strong>Matcher:</strong> All match the given condition</p>'
+          end
+        else
+          @content << "<p class=\"line\"><strong>Matcher:</strong> #{escape(matcher.class.to_s)}</p>"
+        end
+      end
+
+      def result(passed_count, failed_count)
+        summary_class = failed_count > 0 ? 'failure' : 'success'
+        @content << "<p class='result #{summary_class}'><strong>#{passed_count} passed, #{failed_count} failed</strong></p>"
+      end
+
+      def flush
+        @io << document_opening
+        @io << render_index
+        @io << @content
+        @io << '</main></body></html>'
+        super
+      end
+
+      private
+
+      def document_opening
+        <<~HTML
           <html>
             <head>
               <meta charset="utf-8" />
               <meta name="viewport" content="width=device-width, initial-scale=1" />
               <link rel="preconnect" href="https://fonts.googleapis.com">
               <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-              <link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=Source+Sans+3:wght@400;500;600&display=swap" rel="stylesheet">
+              <link href="https://fonts.googleapis.com/css2?family=Saira:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
               <style>
                 :root {
                   --bg: #f3f4f6;
@@ -48,8 +182,42 @@ module PrD
                   border-radius: 18px;
                 }
 
+                .report-index {
+                  background: var(--paper);
+                  border: 1px solid var(--line);
+                  border-radius: 14px;
+                  padding: 0.9rem 1rem;
+                  margin-bottom: 1rem;
+                }
+
+                .index-title {
+                  margin: 0 0 0.6rem;
+                  font-family: "Saira", Georgia, serif;
+                  font-size: 1.15rem;
+                }
+
+                .index-list {
+                  margin: 0;
+                  padding: 0;
+                  list-style: none;
+                }
+
+                .index-item {
+                  margin: 0.2rem 0;
+                  padding-left: calc(var(--index-level, 0) * 1rem);
+                }
+
+                .index-item a {
+                  color: var(--accent);
+                  text-decoration: none;
+                }
+
+                .index-item a:hover {
+                  text-decoration: underline;
+                }
+
                 .context {
-                  font-family: "Fraunces", Georgia, serif;
+                  font-family: "Saira", Georgia, serif;
                   font-size: clamp(1.4rem, 2.8vw, 2rem);
                   margin: 1.3rem 0 1rem;
                   padding-bottom: 0.45rem;
@@ -67,7 +235,7 @@ module PrD
 
                 .test-title {
                   margin: 0 0 0.75rem;
-                  font-family: "Fraunces", Georgia, serif;
+                  font-family: "Saira", Georgia, serif;
                   font-size: 1.2rem;
                 }
 
@@ -153,126 +321,54 @@ module PrD
         HTML
       end
 
-      def context(message)
-        return if synthetic?
-        @io << "<h2 class=\"context\">#{escape(message)}</h2>"
-      end
+      def render_index
+        return '' if @index_entries.empty?
 
-      def success_result(message)
-        if synthetic?
-          @io << "<div class='status success'>PASS</div>"
-          return
-        end
-        @io << "<div class='status success'>✓ #{escape(message)}</div>"
-      end
+        index_items = @index_entries.map do |entry|
+          "<li class=\"index-item\" style=\"--index-level: #{entry[:level]};\"><a href=\"##{entry[:anchor_id]}\">#{escape(index_label(entry))}</a></li>"
+        end.join
 
-      def failure_result(message)
-        if synthetic?
-          @io << "<div class='status failure'>FAIL</div>"
-          return
-        end
-        @io << "<div class='status failure'>✗ #{escape(message)}</div>"
-      end
-
-      def it(description = nil, &block)
-        @current_test_title = description.to_s
-        @io << '<article class="test-card">'
-        @io << "<h3 class=\"test-title\">#{escape(description)}</h3>"
-      end
-
-      def end_it(description = nil, &block)
-        @io << '</article>'
-      end
-
-      def justification(justification)
-        return if synthetic?
-        @io << "<p class=\"line\"><strong>Justification:</strong> #{escape(justification)}</p>"
-      end
-
-      def let(value)
-      end
-
-      def subject(subject)
-        return if synthetic?
-        @io << '<div class="subject-block">'
-        @io << "<p class=\"line\"><strong>Subject:</strong> #{escape(serialize(subject).to_s)}</p>"
-        if image_file?(subject)
-          @io << "<img src=\"#{image_data_uri(subject.path)}\" alt=\"Subject image\" class=\"subject-image\" />"
-        elsif pdf_file?(subject)
-          @io << "<embed src=\"#{pdf_data_uri(subject.path)}\" type=\"application/pdf\" class=\"subject-pdf\" />"
-        elsif pdf_reader?(subject)
-          @io << "<embed src=\"#{pdf_reader_data_uri(subject)}\" type=\"application/pdf\" class=\"subject-pdf\" />"
-        end
-        @io << '</div>'
-      end
-
-      def pending(description = nil)
-        if synthetic?
-          @io << '<article class="test-card">'
-          @io << "<h3 class=\"test-title\">#{escape(description || 'Pending test')}</h3>"
-          @io << "<div class='status pending'>PENDING</div>"
-          @io << '</article>'
-          return
-        end
-        @io << "<div class='status pending'>⚠ #{escape(description || 'Pending test')}</div>"
-        @io << '<p class="line muted">This test is pending and has not been executed.</p>'
-      end
-
-      def expect(expectation)
-        return if synthetic?
-        @io << "<p class=\"line\"><strong>Expect:</strong> #{escape(serialize(expectation).to_s)}</p>"
+        <<~HTML
+          <nav class="report-index" aria-label="Report index">
+            <h2 class="index-title">Index</h2>
+            <ul class="index-list">
+              #{index_items}
+            </ul>
+          </nav>
+        HTML
       end
 
-      def to
-        return if synthetic?
-        @io << '<p class="line"><strong>To:</strong></p>'
-      end
+      def index_label(entry)
+        prefix =
+          case entry[:type]
+          when :context then 'Context'
+          when :pending then 'Pending'
+          else 'Test'
+          end
 
-      def not_to
-        return if synthetic?
-        @io << '<p class="line"><strong>Not to:</strong></p>'
+        "#{prefix}: #{entry[:label]}"
       end
 
-      def matcher(matcher, sources: nil)
-        return if synthetic?
-        case matcher
-        when Matchers::EqMatcher
-          @io << "<p class=\"line\"><strong>Matcher:</strong> Be equal to #{escape(serialize(matcher.expected).to_s)}</p>"
-        when Matchers::BeMatcher
-          @io << "<p class=\"line\"><strong>Matcher:</strong> Be the same object as #{escape(serialize(matcher.expected).to_s)}</p>"
-        when Matchers::IncludesMatcher
-          @io << "<p class=\"line\"><strong>Matcher:</strong> Include #{escape(serialize(matcher.expected).to_s)}</p>"
-        when Matchers::HaveMatcher
-          @io << "<p class=\"line\"><strong>Matcher:</strong> Have #{escape(serialize(matcher.expected).to_s)}</p>"
-        when Matchers::LlmMatcher
-          @io << "<p class=\"line\"><strong>Matcher:</strong> Satisfy condition #{escape(serialize(matcher.expected).to_s)}</p>"
-        when Matchers::AllMatcher
-          if sources
-            code_line = matcher.expected.source_location.last.to_i
-            code = sources.lines[code_line - 1]
-            @io << "<p class=\"line\"><strong>Matcher:</strong> All match condition #{escape(code.strip)}</p>"
-          else
-            @io << '<p class="line"><strong>Matcher:</strong> All match the given condition</p>'
-          end
-        else
-          @io << "<p class=\"line\"><strong>Matcher:</strong> #{escape(matcher.class.to_s)}</p>"
-        end
+      def add_index_entry(type:, label:, level:, anchor_id:)
+        @index_entries << {
+          type:,
+          label: normalize_text(label),
+          level: [level, 0].max,
+          anchor_id:
+        }
       end
 
-      def result(passed_count, failed_count)
-        summary_class = failed_count > 0 ? 'failure' : 'success'
-        @io << "<p class='result #{summary_class}'><strong>#{passed_count} passed, #{failed_count} failed</strong></p>"
+      def next_anchor_id(prefix)
+        @anchor_counters[prefix] += 1
+        "#{prefix}-#{@anchor_counters[prefix]}"
       end
 
-      def flush
-        @io << '</main></body></html>'
-        super
+      def escape(message)
+        CGI.escape_html(normalize_text(message))
       end
 
-      private
-
-      def escape(message)
-        CGI.escape_html(message.to_s)
+      def normalize_text(value)
+        value.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
       end
 
       def image_file?(value)

data/lib/pr_d/formatters/json_formatter.rb

@@ -52,6 +52,11 @@ module PrD
         add_event(type: 'justification', message: justification)
       end
 
+      def let(value)
+        return if synthetic?
+        add_event(type: 'let', value: serialize(value))
+      end
+
       def pending(description = nil)
         if synthetic?
           add_event(type: 'test_result', title: description || 'Pending test', status: 'PENDING')
@@ -104,7 +109,8 @@ module PrD
       private
 
       def add_event(type:, **payload)
-        @events << payload.merge(type:, level: @level)
+        event = payload.merge(type:, level: @level)
+        @events << normalize_for_json(event)
       end
 
       def serialize(value)
@@ -189,6 +195,27 @@ module PrD
           'application/octet-stream'
         end
       end
+
+      def normalize_for_json(value)
+        case value
+        when String
+          value.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
+        when Array
+          value.map { |item| normalize_for_json(item) }
+        when Hash
+          value.each_with_object({}) do |(key, item), normalized|
+            normalized[normalize_hash_key(key)] = normalize_for_json(item)
+          end
+        else
+          value
+        end
+      end
+
+      def normalize_hash_key(key)
+        return key.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?') if key.is_a?(String)
+
+        key
+      end
     end
   end
 end

data/lib/pr_d/formatters/pdf_formatter.rb

@@ -18,6 +18,8 @@ module PrD
         super(io: io, serializers: serializers, mode: mode)
         @events = []
         @summary = { passed: 0, failed: 0 }
+        @index_entries = []
+        @anchor_counters = Hash.new(0)
       end
 
       def title(message)
@@ -26,8 +28,13 @@ module PrD
       end
 
       def context(message)
-        return if synthetic?
-        add_event(:context, message:, level: @level)
+        anchor_id = next_anchor_id('ctx')
+        add_index_entry(type: :context, label: message, level: @level, anchor_id:)
+        if synthetic?
+          add_event(:anchor_marker, message: '', level: @level, anchor_id:)
+          return
+        end
+        add_event(:context, message:, level: @level, anchor_id:)
       end
 
       def success_result(message)
@@ -48,7 +55,9 @@ module PrD
 
       def it(description = nil, &block)
         @current_test_title = description.to_s
-        add_event(:it, message: description.to_s, level: @level)
+        anchor_id = next_anchor_id('test')
+        add_index_entry(type: :test, label: description.to_s, level: @level, anchor_id:)
+        add_event(:it, message: description.to_s, level: @level, anchor_id:)
       end
 
       def end_it(description = nil, &block)
@@ -74,7 +83,10 @@ module PrD
       end
 
       def pending(description = nil)
-        add_event(:pending, message: (description || 'Pending test'), level: @level)
+        pending_label = description || 'Pending test'
+        anchor_id = next_anchor_id('pending')
+        add_index_entry(type: :pending, label: pending_label, level: @level, anchor_id:)
+        add_event(:pending, message: pending_label, level: @level, anchor_id:)
         return if synthetic?
         add_event(:detail, message: 'This test is pending and has not been executed.', level: @level + 1)
       end
@@ -122,6 +134,7 @@ module PrD
       def flush
         document = Prawn::Document.new(page_size: 'A4', margin: 42)
         render_header(document)
+        render_index(document)
         render_events(document)
         render_summary(document)
 
@@ -132,8 +145,22 @@ module PrD
 
       private
 
-      def add_event(type, message:, level:)
-        @events << { type:, message: safe_pdf_text(message.to_s), level: [level, 0].max }
+      def add_event(type, message:, level:, anchor_id: nil)
+        @events << {
+          type:,
+          message: safe_pdf_text(message.to_s),
+          level: [level, 0].max,
+          anchor_id:
+        }
+      end
+
+      def add_index_entry(type:, label:, level:, anchor_id:)
+        @index_entries << {
+          type:,
+          label: safe_pdf_text(label.to_s),
+          level: [level, 0].max,
+          anchor_id:
+        }
       end
 
       def safe_pdf_text(text)
@@ -153,8 +180,40 @@ module PrD
         document.move_down 10
       end
 
+      def render_index(document)
+        return if @index_entries.empty?
+
+        document.fill_color COLORS[:title]
+        document.text 'Index', size: 14, style: :bold
+        document.move_down 4
+
+        @index_entries.each do |entry|
+          document.indent(entry[:level] * 12) do
+            document.formatted_text(
+              [
+                {
+                  text: "- #{index_label(entry)}",
+                  anchor: entry[:anchor_id],
+                  styles: [:underline],
+                  color: COLORS[:context]
+                }
+              ],
+              size: 10
+            )
+          end
+          document.move_down 1
+        end
+
+        document.move_down 8
+        document.stroke_color COLORS[:border]
+        document.stroke_horizontal_rule
+        document.stroke_color '000000'
+        document.move_down 8
+      end
+
       def render_events(document)
         @events.each do |event|
+          register_anchor(document, event)
           case event[:type]
           when :title, :context
             styled_line(document, event[:message], level: event[:level], size: 14, style: :bold, color: COLORS[:context], spacing: 6)
@@ -172,6 +231,8 @@ module PrD
             styled_line(document, event[:message], level: event[:level], size: 10, color: COLORS[:text])
           when :subject_image
             render_image(document, event[:message], level: event[:level])
+          when :anchor_marker
+            next
           when :result
             document.move_down 8
             styled_line(document, event[:message], level: event[:level], size: 11, style: :bold, color: COLORS[:title])
@@ -179,6 +240,13 @@ module PrD
         end
       end
 
+      def register_anchor(document, event)
+        anchor_id = event[:anchor_id]
+        return if anchor_id.nil?
+
+        document.add_dest(anchor_id, document.dest_xyz(0, document.cursor))
+      end
+
       def render_summary(document)
         document.move_down 10
         document.stroke_color COLORS[:border]
@@ -216,6 +284,22 @@ module PrD
         document.move_down 2
       end
 
+      def index_label(entry)
+        prefix =
+          case entry[:type]
+          when :context then 'Context'
+          when :pending then 'Pending'
+          else 'Test'
+          end
+
+        "#{prefix}: #{entry[:label]}"
+      end
+
+      def next_anchor_id(prefix)
+        @anchor_counters[prefix] += 1
+        "#{prefix}-#{@anchor_counters[prefix]}"
+      end
+
       def image_file?(value)
         value.is_a?(File) && value.path.match?(/\.(png|jpe?g)\z/i)
       end

data/lib/pr_d/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrD
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/pr_d.rb

@@ -69,6 +69,8 @@ module PrD
       end
     end
 
+    attr_reader :passed_count, :failed_count
+
     def describe(description, model: nil, &block)
       context(description, model: model, &block)
       @formatter.result(@passed_count, @failed_count)
@@ -185,6 +187,10 @@ module PrD
       @formatter.flush
     end
 
+    def success?
+      @failed_count.zero?
+    end
+
     private
 
     def formatted_time

data/probatio_diabolica.gemspec

@@ -10,13 +10,13 @@ Gem::Specification.new do |spec|
 
   spec.summary       = "A Ruby DSL testing framework with classic and LLM-powered matchers."
   spec.description   = "Probatio Diabolica runs custom *_spec.rb files with a DSL inspired by RSpec and supports text/image/PDF reporting."
-  spec.homepage      = "https://github.com/syadem/probatio_diabolica"
+  spec.homepage      = "https://github.com/mathieulaporte/probatio_diabolica"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 3.1"
 
   spec.metadata = {
-    "source_code_uri" => "https://github.com/syadem/probatio_diabolica",
-    "changelog_uri" => "https://github.com/syadem/probatio_diabolica/releases"
+    "source_code_uri" => "https://github.com/mathieulaporte/probatio_diabolica",
+    "changelog_uri" => "https://github.com/mathieulaporte/probatio_diabolica/releases"
   }
 
   spec.files = Dir[

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: probatio_diabolica
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Laporte Mathieu
@@ -111,12 +111,12 @@ files:
 - lib/pr_d/version.rb
 - lib/probatio_diabolica.rb
 - probatio_diabolica.gemspec
-homepage: https://github.com/syadem/probatio_diabolica
+homepage: https://github.com/mathieulaporte/probatio_diabolica
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/syadem/probatio_diabolica
-  changelog_uri: https://github.com/syadem/probatio_diabolica/releases
+  source_code_uri: https://github.com/mathieulaporte/probatio_diabolica
+  changelog_uri: https://github.com/mathieulaporte/probatio_diabolica/releases
 rdoc_options: []
 require_paths:
 - lib