ui_guardrails 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 792f503cf353ceaa71b9e45e39a4c3f9ae9255b40f4ecf361a207048074857e8
-  data.tar.gz: ff563d0927467149ddc42011500457c7c637db11fc9770566db64e3a0a4427e2
+  metadata.gz: 9f34f9ff613f4b10edd128972a3ee8b268e82fee79abc499d7554d48bf834eec
+  data.tar.gz: 937199143fb681851d6493dc666ce9a381d4db83b247059e00e9b0dd91b8a901
 SHA512:
-  metadata.gz: 3eb224a5d378469571b727813ac68adcacd95576c63bade906a29e4119f9c0b28e972dbbbcf3710acbb6d7647684b14250a28b61c0a52ca65fd2c96e4f435d3a
-  data.tar.gz: 62c132501303b6cc6bcd5ffa8bf566955fc82cf6c4ed30ea3d1ad678ff4270841a57b636daf635035a38681a2e8797ab1e0018ceb62685a144aa840dc3aed238
+  metadata.gz: 8e6d87b9e1bac27c0f79f941343855806c0fb3a3c55b0191cfeb1e184a0b4b5cc6b09eb88ce4df2512ac646c1572f528da269dedacc56fd269f8a4b3ac7630eb
+  data.tar.gz: d50217306f64e883988ad9184adde4d02e274fc8262560aeab3b8a0c9eecd573bae847006c0a3383222020ab3d9281ba96d1720ea9019f17c3491bf21fcf08e1

data/README.md

@@ -1,10 +1,10 @@
-# Guardrails
+# UI-Guardrails
 
 A Rails toolset that prevents UI drift in AI-assisted applications. Static audits over your views, components, stylesheets, JS controllers, and tokens — surfacing the kinds of inconsistencies that compound silently as an AI assistant ships code faster than design-system discipline can keep up.
 
 Built and maintained by [Meticulous](https://meticulous.com).
 
-**Current release:** 1.0.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
+**Current release:** 1.2.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
 
 ---
 

data/doc/RESEARCH-visual-diff.md

@@ -0,0 +1,226 @@
+# Visual-diff integration — research memo
+
+> Status: research, not implementation. Closes the V2 visual-diff item's "evaluate a stable visual-regression target" prerequisite before any code lands.
+>
+> Last updated: 2026-05-10
+
+## Executive summary
+
+**Recommendation: ship a `Guardrails::VisualDiff` parser that consumes screenshot-diff tool output, the same way `Guardrails::A11yDeep` consumes axe-core JSON.** Don't bundle Chromium / Playwright / Capybara as runtime deps — that was the constraint that originally parked this item, and it hasn't changed.
+
+The cleanest external producers to support, in priority order:
+
+1. **`snap_diff-capybara`** (formerly `capybara-screenshot-diff`) — the Rails-native default. Active gem (1.12.0 released April 2026), commits baselines to git, no cloud dep. Highest fit-for-purpose.
+2. **BackstopJS** — fully OSS, clean JSON output. Worth a second adapter for non-Rails-monolith projects (the Avo dogfood pattern).
+3. **Percy / Chromatic** — SaaS, vendor-locked. Defer until a user actually asks; webhook ingestion is the integration shape if they do.
+
+The talk narrative writes itself: **static analysis catches the source, visual diff catches what the rendered DOM does next.** Pair this with `ClassItis` — AI-generated 8-class soup looks plausible in the source but pixel-shifts the baseline once a single utility is wrong.
+
+---
+
+## The constraint that shaped A11yDeep applies here too
+
+When deferring deep a11y in the original roadmap, the call was:
+
+> axe-core wrapper with `--deep` mode NOT shipped — would require Capybara + headless Chrome runtime deps.
+
+Then in 0.6.0 we shipped `A11yDeep` as a **parser** for axe JSON output: zero new runtime deps, user runs axe however they already do, Guardrails provides the merge + report + exit-code contract. The same calculus applies to visual diff. Bundling Playwright/Chromium would balloon `bundle install` for users who don't run system tests; bundling Selenium would tie us to Ruby browser-driver decay. The right move is to consume what existing tools emit.
+
+**Acceptance criteria for any candidate tool**, in priority order:
+
+1. **Emits a machine-readable diff summary** — JSON, JUnit XML, or a parseable HTML/filesystem layout. We need per-scenario: name, baseline path, current path, diff path (if any), mismatch % or pass/fail, optionally the URL/component selector.
+2. **Runs without Guardrails being involved.** The user's existing test toolchain runs the tool; we ingest the output. No shelling out to `npx`, no requiring the tool be present at audit time.
+3. **OSS-friendly licensing** *or* a stable public API for SaaS tools.
+4. **Active maintenance.** Sub-12-month release cadence and >50 GitHub stars as a rough proxy.
+
+---
+
+## Per-tool brief
+
+### snap_diff-capybara (Rails-native) — **PRIMARY RECOMMENDATION**
+
+- **What it is:** Ruby gem (formerly `capybara-screenshot-diff`, now maintained at `github.com/snap-diff/snap_diff-capybara` by `donv` and `jetthoughts`). Latest 1.12.0, April 2026. MIT-licensed. ~770k total downloads.
+- **How it works:** `screenshot "name"` inside Capybara system tests. Baselines live at `doc/screenshots/` and are **committed to git** — UI changes get reviewed in PR like code. No external auth, no cloud.
+- **Diff artifacts:**
+  - `*.png` baseline
+  - `*.diff.png` (changed pixels highlighted red)
+  - `*.heatmap.diff.png` (pixel-variance density)
+  - **`snap_diff_report.html`** — interactive multi-view dashboard
+- **CI flow:** Tests fail on baseline mismatch. There's a reusable GitHub Actions workflow that uploads the HTML report and posts PR comments. Ships its own baseline-update flow.
+- **Runtime:** Ruby 3.2+, any Capybara-compatible driver (Selenium / Playwright / Cuprite). libvips 8.9+ for fast comparisons, falls back to ChunkyPNG.
+- **For Guardrails to consume:** the HTML report has a fixed structure, but the gem doesn't (yet) emit a top-level JSON summary. **Either:**
+  - **(a)** ask upstream for a `snap_diff_report.json` companion to the HTML — small ask, this is the maintained gem
+  - **(b)** walk `doc/screenshots/` ourselves: pair `name.png` with `name.diff.png`, treat presence of the diff file as a failing finding
+- **Fit:** ★★★★★. Same ecosystem (Ruby/Rails/Capybara), no new deps for users already running system tests, baselines-in-git matches the Guardrails ethos of "the source is the source of truth."
+
+### BackstopJS
+
+- **What it is:** Node CLI, MIT-licensed, actively maintained, the dominant OSS visual-regression tool outside the Storybook ecosystem.
+- **How it works:** `backstop init`, `backstop test`, `backstop approve`. Configured via `backstop.json` (scenarios = URL × viewport × selector). Headless Chrome via Puppeteer or Firefox/WebKit via Playwright. All artifacts local under `backstop_data/`.
+- **Output:** HTML interactive report, **JSON report**, JUnit XML, CLI text. Exit 0/1.
+- **For Guardrails to consume:** The JSON report already exists and is the canonical machine-readable output. Per-scenario: name, label, mismatch percentage, pass/fail, paths to reference + test + diff images.
+- **Fit:** ★★★★☆. Native machine-readable output, no SaaS dep, but Node-only — Ruby/Rails shops would have a parallel toolchain. Justifiable for the "Rails frontend that already runs JS tooling" subset (any non-trivial Rails app).
+
+### Playwright `toHaveScreenshot` / `toMatchSnapshot`
+
+- **What it is:** Built-in Playwright assertion. The team that maintains Playwright also maintains Chromatic (Microsoft → Storybook acquisition), so it's becoming the de facto cross-tool snapshot mechanism.
+- **How it works:** `await expect(page).toHaveScreenshot()`. Stores baselines in `__screenshots__/`. Updates via `--update-snapshots`.
+- **Output:** JUnit / JSON via Playwright's reporter API; HTML report; per-test pass/fail in CI.
+- **For Guardrails to consume:** Playwright JSON reporter emits a structured test-result document; each failure includes `attachments` with the diff image path. Parseable, but the schema is "Playwright test results" not "visual diff" — we'd be extracting the visual subset.
+- **Fit:** ★★★☆☆. Future-proof and increasingly canonical, but the integration is heavier (have to filter Playwright results for screenshot-specific failures). Worth supporting in v2 of the adapter.
+
+### Percy (BrowserStack)
+
+- **What it is:** SaaS, all builds go through Percy's cloud. Originally a standalone product, BrowserStack-acquired in 2020.
+- **Ruby story:** `percy-capybara` gem exists. Latest release v5.0.0 — July 2021 — i.e. **maintenance-stale**. 4+ years without a meaningful release; the active surface is the JS SDKs.
+- **Output:** Dashboard URL + per-build webhook. No local artifacts beyond the snapshot upload.
+- **Pricing:** Pricing page is gated behind BrowserStack's product navigation; no clear OSS-free tier surfaced via the public site. Assume paid-only for non-trial use.
+- **For Guardrails to consume:** `build-finished` webhook payload is the integration shape — but that requires a receiver, which Guardrails-the-gem isn't. Could ship a parser for the webhook JSON that users POST to their CI.
+- **Fit:** ★★☆☆☆. Stale Ruby SDK, vendor-locked, no clear OSS pricing. Defer until a user asks specifically.
+
+### Chromatic
+
+- **What it is:** SaaS, made by the Storybook team. The standard visual-regression for Storybook-based component libraries; expanded to Playwright + Cypress in 2024–25.
+- **Ruby story:** None. JS-ecosystem only. No Lookbook integration despite Lookbook being the Rails-shaped Storybook equivalent.
+- **Output:** Cloud dashboard, web API for build status, no local artifacts.
+- **Pricing:** Free tier (5,000 snapshots/month, Chrome-only) — generous. Paid starts at $179/mo. "Building in the open?" OSS plan available on application.
+- **Fit:** ★★☆☆☆ for Rails apps without Storybook. ★★★★☆ for ViewComponent shops who use Storybook for non-Rails components alongside. Pair-of-tools story is workable but indirect; Lookbook integration would be the missing link, and that's a Lookbook upstream ask, not a Guardrails one.
+
+### Honorable mentions
+
+- **Loki** — Storybook-only, narrow audience for Rails-flavored Guardrails. Skip.
+- **`reg-suit`** — Cloud or self-hosted, language-agnostic, JSON report. Reasonable BackstopJS-alternative; not common enough in Rails shops to justify a dedicated adapter at v1.
+
+---
+
+## Fit table
+
+| Tool | OSS | Rails-native | Machine-readable output | Cloud dep | Active | Fit score |
+|---|---|---|---|---|---|---|
+| snap_diff-capybara | ✅ MIT | ✅ Ruby gem | 🟡 HTML report (no JSON yet) | ❌ baselines in git | ✅ active | ★★★★★ |
+| BackstopJS | ✅ MIT | ❌ Node | ✅ JSON report | ❌ local FS | ✅ active | ★★★★☆ |
+| Playwright snapshots | ✅ Apache | ❌ Node | ✅ JSON via reporter | ❌ local FS | ✅ active | ★★★☆☆ |
+| Percy | 🔒 SaaS | 🟡 stale gem (2021) | ✅ webhook | ✅ required | 🟡 webhooks active, SDK stale | ★★☆☆☆ |
+| Chromatic | 🔒 SaaS | ❌ JS-only | ✅ API | ✅ required | ✅ active | ★★☆☆☆ |
+
+---
+
+## Proposed integration shape (mirrors A11yDeep)
+
+```
+lib/guardrails/visual_diff.rb           — parser + report
+lib/guardrails/visual_diff/snap_diff.rb — adapter for snap_diff-capybara
+lib/guardrails/visual_diff/backstop.rb  — adapter for BackstopJS JSON
+spec/guardrails/visual_diff_spec.rb
+spec/guardrails/visual_diff/snap_diff_spec.rb
+spec/guardrails/visual_diff/backstop_spec.rb
+```
+
+Normalized `Finding` shape (across both adapters):
+
+```ruby
+Finding = Struct.new(
+  :scenario,        # "homepage", "checkout_cart"
+  :viewport,        # "desktop"; nil if not applicable
+  :mismatch_ratio,  # Float 0.0..1.0 (or nil for snap_diff which is pass/fail)
+  :baseline_path,   # relative path on disk
+  :current_path,    # relative path on disk
+  :diff_path,       # relative path to .diff.png, nil if pass
+  :url,             # optional, BackstopJS scenarios have URLs
+  :selector,        # optional
+  keyword_init: true
+)
+```
+
+Rake task (mirrors `guardrails:a11y:deep`):
+
+```bash
+# Either auto-detect from `doc/screenshots/` (snap_diff convention) ...
+bundle exec rake guardrails:visual:deep
+
+# ... or point at an explicit producer:
+SNAP_DIFF_DIR=doc/screenshots bundle exec rake guardrails:visual:deep
+BACKSTOP_JSON=backstop_data/html_report/jsonReport.json bundle exec rake guardrails:visual:deep
+```
+
+Folded into `guardrails:audit` via `VISUAL_DIFF=...` env var, same shape as `AXE_JSON`.
+
+JSON output extends the existing audit payload:
+
+```json
+{
+  "summary": { "...": "...", "visual_diff": 3 },
+  "visual_diff": [
+    { "scenario": "checkout/cart", "mismatch_ratio": 0.082,
+      "baseline_path": "doc/screenshots/checkout_cart.png",
+      "diff_path": "doc/screenshots/checkout_cart.diff.png" }
+  ]
+}
+```
+
+Exit-code contract: a finding's `mismatch_ratio > threshold` (configurable, default `0.0` — any diff fails) bumps the audit to exit 1. For snap_diff (pass/fail), any failure is a fail.
+
+---
+
+## What this buys the gem (and the talk)
+
+1. **Closes V2.** Roadmap is fully shipped on the three core items.
+2. **Talk narrative is now four layers deep:**
+   - *Static AST drift* (V0): the source-level mistakes.
+   - *Structural drift* (V2 cross-codebase + class-itis): the patterns the source shouldn't have.
+   - *Runtime a11y drift* (V1.6 deep a11y): what the static checks can't see.
+   - *Visual drift* (V2 visual-diff): what the rendered DOM does next.
+
+   AI assistants fail at each layer differently. Each Guardrails detector maps to a specific failure mode.
+
+3. **Same install/run story as everything else.** No new install footprint. Users keep their preferred screenshot tool; Guardrails provides the unified report.
+
+---
+
+## Open decisions for the morning
+
+1. **Primary adapter: snap_diff or BackstopJS?**
+   - My read: snap_diff-capybara, since (a) Rails-native, (b) we'd be working with the maintainers of a small focused gem who'd likely accept a JSON-output PR upstream, and (c) baselines-in-git matches Guardrails' "source is canonical" ethos.
+   - The risk: snap_diff doesn't currently emit JSON, so v0.8.0 might need an upstream contribution. We could ship the filesystem-walking adapter first (look at `doc/screenshots/*.diff.png`) and contribute the JSON emitter separately.
+
+2. **Scope: ship one adapter or two?**
+   - One (snap_diff) keeps the PR small and proves the pattern.
+   - Two (snap_diff + BackstopJS) covers the Avo / non-Rails-monolith case from day one.
+   - I'd ship one and tag, then add BackstopJS in a follow-up if there's signal.
+
+3. **Threshold default: `0.0` (any diff fails) or something more lenient?**
+   - A11yDeep defaulted to "any non-nil impact fails". The visual-diff equivalent is "any pixel mismatch fails" — strict, but visual diff is opt-in (you set up baselines deliberately), so strict is the right default.
+   - Per-call override via `VISUAL_DIFF_THRESHOLD=0.01` env or `visual_diff.threshold` in `guardrails.yml`.
+
+4. **Where does this surface in the Lookbook panel?**
+   - `ComponentReport#for` could add `visual_diff: [...]` showing per-component baseline mismatches. Pulls together: "this component drifted statically (raw_color) AND visually (3% mismatch on the desktop viewport)."
+   - Probably out of scope for v0.8.0 — first land the audit/CI integration, layer Lookbook in v0.9.0.
+
+5. **Is this 0.8.0 or 1.0.0?**
+   - Argument for 0.8.0: matches the pattern of every other increment.
+   - Argument for 1.0.0: with this shipped, all three V0–V2 column-headers are done. We could draw the "ready for serious use" line here and tag a 1.0.0.
+   - My read: 0.8.0 for the visual-diff feature, then a separate 1.0.0 release after dogfooding the full V2 surface against Patchvault/Talos/Forem/Avo. The 0.2.x→0.7.x cadence already moved through dogfood-driven patches; another round before 1.0.0 fits.
+
+---
+
+## Out of scope
+
+- **Running the screenshot tool ourselves.** Not now, possibly not ever — the gem's ethos is parse-only.
+- **Hosted baseline storage.** Baselines stay in the user's repo (snap_diff convention) or wherever their existing tool puts them.
+- **Image-diff algorithm work.** Pixel comparison is a solved problem with multiple good libraries; we don't add value by reinventing it.
+- **Real-browser rendering.** Same as the headless Chrome reasoning in A11yDeep.
+
+---
+
+## What's needed to start
+
+If we go with snap_diff-capybara as the primary adapter:
+
+1. Decide if we file an upstream PR to add `snap_diff_report.json` emission, or build the filesystem-walking adapter first.
+2. Add `snap_diff-capybara` to `examples/demo/Gemfile` and seed a couple of system tests so the integration spec has something to verify against.
+3. Roughly 3 slices, mirroring the A11yDeep PR:
+   - Slice 1: `VisualDiff` parser + `Finding` struct + snap_diff adapter + spec
+   - Slice 2: rake task wiring (standalone + `guardrails:audit` fold-in) + JSON output extension
+   - Slice 3: docs (new `doc/VISUAL-DIFF.md` mirroring `doc/A11Y.md`) + ROADMAP + CHANGELOG → 0.8.0
+
+Estimated scope: a single PR, comparable to 0.6.0's `A11yDeep` (~17 specs, ~400 LOC). Could be shipped same day as kick-off if no upstream blocker.

data/lib/guardrails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Guardrails
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - John Athayde
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: herb
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +79,7 @@ files:
 - doc/LOOKBOOK.md
 - doc/PRD.md
 - doc/PUBLISHING.md
+- doc/RESEARCH-visual-diff.md
 - doc/ROADMAP.md
 - doc/UPSTREAM-snap_diff-issue-draft.md
 - doc/VISUAL-DIFF.md
@@ -125,7 +125,6 @@ metadata:
   source_code_uri: https://github.com/meticulous/guardrails
   changelog_uri: https://github.com/meticulous/guardrails/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -133,15 +132,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails toolset for preventing UI drift in AI-assisted applications.
 test_files: []