probatio_diabolica 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 368faf074dc354becfef975422fc3199a1e83293a30bad935ef17696a9b879c9
-  data.tar.gz: 66b84421f306926f425cdc6d9e5cc4a1ff3b8ed1cd4f6df13e86bd7313796c5d
+  metadata.gz: 39336802d7f3c344f21acbf0567ea85a73dfbc68c2d339e7ab5e1e1866fc609e
+  data.tar.gz: c4f0fa5209ac0a7437edf9e6cf117b95fe859217b49e172557f05c44dc664307
 SHA512:
-  metadata.gz: f9cce79af416cc2b0e216820dd3f07f2d0ba46552db2e2598d9ab2ab83f1492757044717a383256db7b6d14168a3da4d11a0cf89949f6ec1eebe4bf55f366f2c
-  data.tar.gz: 03e7a8a23b02b473e8bac35c4b4021e729b4e435408bdc69a6143162eebdad8172ec5bb07b83d4471b87464c5f42b1346a112d0e1d7f3af061f916838ea13ea8
+  metadata.gz: f78a5ff31c1b5cbee275d596ef74529b0fad41426c4b7ee5303d98d4224cbcf20718485403ec048fc4f26159775c0ae8e33c07eeeb95e6944c2a21cf3feeec26
+  data.tar.gz: ffa412e8bc62906e1c9be463a9d48dc9a30bbf4e4fcf458abc1e203026bde0a7e5f60ae0dce03c33cd6375c5402060b80ae1b1cf0b610328b1808a5eb436b8cf

data/README.md

@@ -21,7 +21,7 @@ Tests are evaluated with `instance_eval` (not through RSpec).
 
 ## Installation
 
-### From the gem
+### In the Gemfile
 
 ```ruby
 gem 'probatio_diabolica'
@@ -33,63 +33,6 @@ Then:
 bundle install
 ```
 
-In Ruby code, you can load it with:
-
-```ruby
-require "probatio_diabolica"
-```
-
-### From this repository (local development)
-
-```bash
-bundle install
-bundle exec prd examples/basics_spec.rb
-```
-
-### Build and install as a gem
-
-```bash
-# build the package
-gem build probatio_diabolica.gemspec
-
-# install locally from the built gem
-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
-prd examples/basics_spec.rb
-```
-
-If `prd` is not found, add your gem bin directory to `PATH`:
-
-```bash
-export PATH="$(ruby -e 'print Gem.user_dir')/bin:$PATH"
-```
-
 ## Configuration LLM
 
 The runtime automatically loads `prd_helper.rb` if present (or a file passed with `-c`).
@@ -119,6 +62,29 @@ From source checkout (without gem install), this is always valid:
 bundle exec ruby bin/prd <file_or_directory> [options]
 ```
 
+## MCP server (`run_specs`)
+
+A minimal MCP server is available through:
+
+```bash
+bundle exec ruby bin/prd_mcp
+```
+
+It exposes one tool: `run_specs`.
+
+Input:
+- `path` (required): file or directory containing specs
+- `config` (optional): same as `-c`
+- `out` (optional): same as `-o`
+- `formatters` (optional): array of `simple|html|json|pdf` (default: `["simple"]`)
+- `mode` (optional): `verbose|synthetic` (default: `synthetic`)
+
+Output (`structuredContent`):
+- `ok`, `exit_code`
+- `summary` (`passed`, `failed`, `pending`)
+- `artifacts` (`base_out`, `reports`, `annex_dir`)
+- `logs` (`stdout`, `stderr`)
+
 Options:
 
 - `-c, --config FILE` Ruby config file to require
@@ -151,33 +117,36 @@ Examples:
 
 ```bash
 # single file
-bundle exec ruby bin/prd examples/basics_spec.rb
+prd examples/basics_spec.rb
 
 # all *_spec.rb files in a directory
-bundle exec ruby bin/prd examples
+prd examples
 
 # HTML report in an existing directory (creates ./tmp/report.html)
-bundle exec ruby bin/prd examples/image_spec.rb -t html -o ./tmp/
+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
+prd examples/basics_spec.rb -t html,json,pdf -o ./tmp/my_report
 
 # compact synthetic output on console
-bundle exec ruby bin/prd examples/basics_spec.rb --mode synthetic
+prd examples/basics_spec.rb --mode synthetic
 ```
 
 ## Available DSL
 
+It is inspired by RSpec but with a custom runtime and additional features.
+
 ### Structure
 
 ```ruby
 describe 'My domain' do
   context 'my context' do
-    let(:value) { 5 }
-    subject { 'hello' }
+    let(:two) { 2 }
+    let(:three) { 3 }
+    subject { two + three }
 
     it 'runs an assertion' do
-      expect(value).to eq(5)
+      expect.to eq(5)
     end
 
     pending 'test to implement later'
@@ -192,6 +161,42 @@ end
 - `expect { |subject| ... }.to matcher`
 - `expect.to matcher` (uses `subject`)
 
+### Spec best practices for `subject` (PRD reports)
+
+When a test defines a `subject`, PRD can surface it more clearly in generated reports.
+For CLI and integration specs, prefer:
+
+- grouping with explicit `context`
+- one `subject` per context for the main action
+- assertions written with `expect.to(...)` when the assertion targets `subject`
+
+Example:
+
+```ruby
+context 'when CLI receives an unknown formatter type' do
+  subject { Open3.capture3('bundle exec ruby bin/prd spec/self_hosted_spec.rb -t unknown') }
+
+  it 'fails fast on unknown formatter type in CLI' do
+    _stdout, stderr, status = subject
+
+    expect(status.success?).to(be(false))
+    expect(stderr).to(includes('Unsupported formatter type: unknown. Supported: simple, html, json, pdf'))
+  end
+end
+```
+
+For simple value checks, this pattern keeps specs concise:
+
+```ruby
+context 'with strings' do
+  subject { 'probatio diabolica' }
+
+  it 'matches expected content' do
+    expect.to(includes('diabolica'))
+  end
+end
+```
+
 ### Matchers
 
 - `eq(expected)` equality with `==`
@@ -205,13 +210,30 @@ end
 
 `PrD::Runtime` exposes helpers to test content loaded in Chrome:
 
+- `page(at:, warmup_time:)` opens a page and returns a `BrowserSession`
 - `screen(at:, width:, height:, warmup_time:)` captures a PNG and returns a `File`
-- `text(at:, css:, warmup_time:)` extracts a CSS node into a `.txt` file and returns a `File`
+- `text(at:, css:, warmup_time:)` extracts a CSS node and returns `PrD::Code` (language: `text`)
 - `network(at:, warmup_time:)` returns Ferrum network traffic
 - `network_urls(at:, warmup_time:)` returns traffic URLs
 - `pdf(at:, warmup_time:)` generates a PDF and returns a `PDF::Reader`
 - `html(at:, warmup_time:)` returns HTML (`browser.body`)
 
+`BrowserSession` adds high-level page interactions:
+
+- `find(css:/xpath:, wait:, shadow:)`
+- `exists?(css:/xpath:, wait:, shadow:)`
+- `click(css:/xpath:, wait:, shadow:)`
+- `fill(css:/xpath:, with:, clear:, blur:, wait:, shadow:)`
+- `select_option(css:, value:/values:, by:, wait:, shadow:)`
+- `set_files(css:, path:/paths:, wait:, shadow:)` (alias `upload_files`)
+- `navigate(to:, warmup_time:)`
+
+About `shadow:`:
+
+- `shadow:` is an ordered CSS path used to narrow the scope before the target selector.
+- Each step can be a shadow host or a regular container.
+- If a step has `shadowRoot`, search continues inside it; otherwise search continues inside the matched node.
+
 Prerequisites:
 
 - Chrome/Chromium must be installed.
@@ -228,9 +250,39 @@ it 'checks dynamic content loaded in browser' do
 end
 ```
 
+Form interaction and file upload example:
+
+```ruby
+it 'uploads a file in a shadow-dom form' do
+  html(at: 'https://example.com/upload', warmup_time: 2) do |page|
+    page.click(css: 'button[data-open-upload]')
+    page.fill(css: 'input[name="title"]', with: 'Invoice')
+    page.set_files(
+      css: 'input[type="file"]',
+      shadow: ['vax-scanner', '[data-view="upload"]'],
+      path: 'examples/random_photo.png'
+    )
+  end
+end
+```
+
 ### Source code helper (Prism)
 
 `source_code(...)` uses the `prism` gem to parse Ruby source and extract class/method code.
+It returns a `PrD::Code` object:
+
+- `source` (`String`)
+- `language` (`String`, default: `ruby`)
+
+Example:
+
+```ruby
+let(:code) { source_code(PrD::Matchers::AllMatcher) }
+
+it 'uses raw source text' do
+  expect(code.source).to(includes('class AllMatcher'))
+end
+```
 
 Prerequisites:
 
@@ -273,13 +325,16 @@ When you define a `subject`, each formatter tries to render it in the most usefu
   - for files, prints a textual representation (for example path, file preview for `.txt`)
 - `HtmlFormatter`:
   - renders text values directly
+  - for `PrD::Code`, renders syntax-highlighted code blocks (Rouge) inside collapsible sections
   - for image files (`.png`, `.jpg`, `.jpeg`), embeds the image in the report
   - for PDF subjects (`File` `.pdf` or `PDF::Reader`), embeds the PDF with a `data:application/pdf;base64,...` URI
 - `PdfFormatter`:
   - renders text values as report lines
+  - for `PrD::Code`, renders language + syntax-highlighted code block (Rouge -> Prawn colors)
   - for image files (`.png`, `.jpg`, `.jpeg`), inserts the image directly in the PDF report
 - `JsonFormatter`:
   - keeps a structured representation for machine processing
+  - for `PrD::Code`, emits a structured payload (`type: "code"`, `language`, `source`)
   - `File` values (images, PDFs, text files, etc.) are embedded as base64 payloads
   - `PDF::Reader` values are also embedded as base64 (`application/pdf`)
 

data/bin/prd_mcp

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'pr_d'
+rescue LoadError
+  require_relative '../lib/pr_d'
+end
+
+PrD::Mcp::Server.new.run

data/lib/pr_d/code.rb

@@ -0,0 +1,19 @@
+module PrD
+  class Code < SimpleDelegator
+    attr_reader :source, :language
+
+    def initialize(source:, language: 'ruby')
+      super(source.to_s)
+      @source = source.to_s
+      @language = language.to_s
+    end
+
+    def to_s
+      @source
+    end
+
+    def include?(value)
+      @source.include?(value)
+    end
+  end
+end

data/lib/pr_d/formatters/formatter.rb

@@ -100,6 +100,10 @@ module PrD
 
         value
       end
+
+      def code_object?(value)
+        defined?(PrD::Code) && value.is_a?(PrD::Code)
+      end
     end
   end
 end

data/lib/pr_d/formatters/html_formatter.rb

@@ -1,5 +1,6 @@
 require 'cgi'
 require 'base64'
+require 'rouge'
 
 module PrD
   module Formatters
@@ -9,6 +10,7 @@ module PrD
         @content = +''
         @index_entries = []
         @anchor_counters = Hash.new(0)
+        @rouge_formatter = Rouge::Formatters::HTMLLegacy.new(css_class: 'highlight')
       end
 
       def context(message)
@@ -51,20 +53,13 @@ module PrD
       end
 
       def let(value)
+        return if synthetic?
+        render_value_block('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>'
+        render_value_block('Subject', subject)
       end
 
       def pending(description = nil)
@@ -85,7 +80,7 @@ module PrD
 
       def expect(expectation)
         return if synthetic?
-        @content << "<p class=\"line\"><strong>Expect:</strong> #{escape(serialize(expectation).to_s)}</p>"
+        render_labeled_value('Expect', expectation)
       end
 
       def to
@@ -102,15 +97,15 @@ module PrD
         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>"
+          render_matcher_value('Be equal to', matcher.expected)
         when Matchers::BeMatcher
-          @content << "<p class=\"line\"><strong>Matcher:</strong> Be the same object as #{escape(serialize(matcher.expected).to_s)}</p>"
+          render_matcher_value('Be the same object as', matcher.expected)
         when Matchers::IncludesMatcher
-          @content << "<p class=\"line\"><strong>Matcher:</strong> Include #{escape(serialize(matcher.expected).to_s)}</p>"
+          render_matcher_value('Include', matcher.expected)
         when Matchers::HaveMatcher
-          @content << "<p class=\"line\"><strong>Matcher:</strong> Have #{escape(serialize(matcher.expected).to_s)}</p>"
+          render_matcher_value('Have', matcher.expected)
         when Matchers::LlmMatcher
-          @content << "<p class=\"line\"><strong>Matcher:</strong> Satisfy condition #{escape(serialize(matcher.expected).to_s)}</p>"
+          render_matcher_value('Satisfy condition', matcher.expected)
         when Matchers::AllMatcher
           if sources
             code_line = matcher.expected.source_location.last.to_i
@@ -156,6 +151,7 @@ module PrD
                   --muted: #6b7280;
                   --line: #e5e7eb;
                   --accent: #0f766e;
+                  --sidebar-width: 320px;
                   --pass-bg: #ecfdf5;
                   --pass-fg: #166534;
                   --fail-bg: #fef2f2;
@@ -182,12 +178,51 @@ module PrD
                   border-radius: 18px;
                 }
 
+                body.has-index main.container {
+                  width: min(960px, calc(100% - var(--sidebar-width) - 4rem));
+                  margin: 1rem 1rem 2rem calc(var(--sidebar-width) + 2rem);
+                }
+
+                body.has-index.index-collapsed main.container {
+                  width: min(960px, calc(100% - 2rem));
+                  margin: 1rem auto 2rem;
+                }
+
+                .index-toggle {
+                  position: fixed;
+                  top: 0.9rem;
+                  left: 0.9rem;
+                  z-index: 1100;
+                  border: 1px solid #d1d5db;
+                  border-radius: 999px;
+                  background: var(--paper);
+                  color: #0f172a;
+                  padding: 0.45rem 0.8rem;
+                  font-size: 0.9rem;
+                  font-weight: 600;
+                  cursor: pointer;
+                  box-shadow: 0 6px 18px rgba(15, 23, 42, 0.12);
+                }
+
                 .report-index {
+                  position: fixed;
+                  top: 3.2rem;
+                  left: 1rem;
+                  bottom: 1rem;
+                  z-index: 1000;
+                  width: var(--sidebar-width);
                   background: var(--paper);
                   border: 1px solid var(--line);
                   border-radius: 14px;
                   padding: 0.9rem 1rem;
-                  margin-bottom: 1rem;
+                  overflow-y: auto;
+                  transition: transform 0.18s ease, opacity 0.18s ease;
+                }
+
+                body.has-index.index-collapsed .report-index {
+                  transform: translateX(calc(-1 * (var(--sidebar-width) + 1rem)));
+                  opacity: 0;
+                  pointer-events: none;
                 }
 
                 .index-title {
@@ -207,12 +242,16 @@ module PrD
                   padding-left: calc(var(--index-level, 0) * 1rem);
                 }
 
-                .index-item a {
+                .index-link {
+                  display: block;
+                  white-space: nowrap;
+                  overflow: hidden;
+                  text-overflow: ellipsis;
                   color: var(--accent);
                   text-decoration: none;
                 }
 
-                .index-item a:hover {
+                .index-link:hover {
                   text-decoration: underline;
                 }
 
@@ -314,6 +353,83 @@ module PrD
                 .result.success { color: var(--pass-fg); background: var(--pass-bg); }
                 .result.failure { color: var(--fail-fg); background: var(--fail-bg); }
                 .muted { color: var(--muted); }
+
+                .code-language {
+                  color: var(--muted);
+                  font-size: 0.85rem;
+                  text-transform: uppercase;
+                  letter-spacing: 0.05em;
+                }
+
+                .code-block {
+                  margin: 0.45rem 0 0.7rem;
+                  border: 1px solid var(--line);
+                  border-radius: 10px;
+                  background: #fff;
+                }
+
+                .code-toggle {
+                  list-style: none;
+                  cursor: pointer;
+                  padding: 0.6rem 0.8rem;
+                  display: flex;
+                  align-items: center;
+                  justify-content: space-between;
+                  gap: 0.8rem;
+                  font-size: 0.88rem;
+                  color: var(--text);
+                }
+
+                .code-toggle::-webkit-details-marker {
+                  display: none;
+                }
+
+                .code-toggle::after {
+                  content: 'Open';
+                  color: var(--muted);
+                  font-size: 0.78rem;
+                  letter-spacing: 0.03em;
+                  text-transform: uppercase;
+                }
+
+                .code-block[open] .code-toggle::after {
+                  content: 'Close';
+                }
+
+                .highlight {
+                  margin: 0;
+                  border-top: 1px solid var(--line);
+                  border-radius: 0 0 10px 10px;
+                  overflow-x: auto;
+                }
+
+                .highlight pre {
+                  margin: 0;
+                  padding: 0.8rem;
+                  line-height: 1.35;
+                }
+
+                @media (max-width: 960px) {
+                  :root { --sidebar-width: min(82vw, 320px); }
+
+                  body.has-index main.container,
+                  body.has-index.index-collapsed main.container {
+                    width: calc(100% - 1rem);
+                    margin: 4rem 0.5rem 1rem 0.5rem;
+                  }
+
+                  .report-index {
+                    top: 3.5rem;
+                    left: 0.5rem;
+                    bottom: 0.5rem;
+                  }
+
+                  body.has-index.index-collapsed .report-index {
+                    transform: translateX(calc(-1 * (var(--sidebar-width) + 0.6rem)));
+                  }
+                }
+
+                #{rouge_theme_css}
               </style>
             </head>
             <body>
@@ -325,28 +441,52 @@ module PrD
         return '' if @index_entries.empty?
 
         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>"
+          label = escape(index_label(entry))
+          "<li class=\"index-item\" style=\"--index-level: #{entry[:level]};\"><a class=\"index-link\" href=\"##{entry[:anchor_id]}\" title=\"#{label}\">#{label}</a></li>"
         end.join
 
         <<~HTML
-          <nav class="report-index" aria-label="Report index">
+          <button type="button" class="index-toggle" aria-expanded="false" aria-controls="report-index">Show index</button>
+          <nav id="report-index" class="report-index" aria-label="Report index">
             <h2 class="index-title">Index</h2>
             <ul class="index-list">
               #{index_items}
             </ul>
           </nav>
+          <script>
+            (function() {
+              var body = document.body;
+              var nav = document.getElementById('report-index');
+              var toggle = document.querySelector('.index-toggle');
+              if (!body || !nav || !toggle) return;
+
+              body.classList.add('has-index');
+
+              var syncToggleLabel = function() {
+                var isCollapsed = body.classList.contains('index-collapsed');
+                toggle.setAttribute('aria-expanded', String(!isCollapsed));
+                toggle.textContent = isCollapsed ? 'Show index' : 'Hide index';
+              };
+
+              toggle.addEventListener('click', function() {
+                body.classList.toggle('index-collapsed');
+                syncToggleLabel();
+              });
+
+              syncToggleLabel();
+            })();
+          </script>
         HTML
       end
 
       def index_label(entry)
-        prefix =
+        marker =
           case entry[:type]
-          when :context then 'Context'
-          when :pending then 'Pending'
-          else 'Test'
+          when :context then '+'
+          else '-'
           end
 
-        "#{prefix}: #{entry[:label]}"
+        "#{marker} #{entry[:label]}"
       end
 
       def add_index_entry(type:, label:, level:, anchor_id:)
@@ -363,6 +503,72 @@ module PrD
         "#{prefix}-#{@anchor_counters[prefix]}"
       end
 
+      def render_labeled_value(label, value)
+        if code_object?(value)
+          @content << "<p class=\"line\"><strong>#{escape(label)}:</strong></p>"
+          @content << render_code_block(value)
+        else
+          @content << "<p class=\"line\"><strong>#{escape(label)}:</strong> #{escape(serialize(value).to_s)}</p>"
+        end
+      end
+
+      def render_matcher_value(label, value)
+        if code_object?(value)
+          @content << "<p class=\"line\"><strong>Matcher:</strong> #{escape(label)} (#{escape(value.language)})</p>"
+          @content << render_code_block(value)
+        else
+          @content << "<p class=\"line\"><strong>Matcher:</strong> #{escape(label)} #{escape(serialize(value).to_s)}</p>"
+        end
+      end
+
+      def render_value_block(label, value)
+        @content << '<div class="subject-block">'
+        if code_object?(value)
+          @content << "<p class=\"line\"><strong>#{escape(label)}:</strong></p>"
+          @content << render_code_block(value)
+        else
+          @content << "<p class=\"line\"><strong>#{escape(label)}:</strong> #{escape(serialize(value).to_s)}</p>"
+        end
+
+        if image_file?(value)
+          @content << "<img src=\"#{image_data_uri(value.path)}\" alt=\"#{escape(label)} image\" class=\"subject-image\" />"
+        elsif pdf_file?(value)
+          @content << "<embed src=\"#{pdf_data_uri(value.path)}\" type=\"application/pdf\" class=\"subject-pdf\" />"
+        elsif pdf_reader?(value)
+          @content << "<embed src=\"#{pdf_reader_data_uri(value)}\" type=\"application/pdf\" class=\"subject-pdf\" />"
+        end
+        @content << '</div>'
+      end
+
+      def render_code_block(code)
+        source = normalize_text(code.source)
+        language = normalize_text(code.language)
+        highlighted = highlight_code(source, language)
+        <<~HTML
+          <details class="code-block">
+            <summary class="code-toggle">
+              <span class="code-language">#{escape(language)}</span>
+            </summary>
+            #{highlighted}
+          </details>
+        HTML
+      end
+
+      def highlight_code(source, language)
+        lexer = rouge_lexer_for(source, language)
+        @rouge_formatter.format(lexer.lex(source))
+      end
+
+      def rouge_lexer_for(source, language)
+        Rouge::Lexer.find_fancy(language, source) || Rouge::Lexers::PlainText
+      rescue StandardError
+        Rouge::Lexers::PlainText
+      end
+
+      def rouge_theme_css
+        Rouge::Themes::Github.render(scope: '.highlight')
+      end
+
       def escape(message)
         CGI.escape_html(normalize_text(message))
       end