ui_guardrails 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b29232255e89ade665ffe0aa02661183fbf71c5918c53704d8241293be757454
-  data.tar.gz: 5d3cf78b2091bb6e781f6bd563976c9bc1c583a8269309ce897ed90d8eae3b3b
+  metadata.gz: a0bae61006af0fcdb91d543ab37539ed5f01bc653faa3a1732b56ee4f450d075
+  data.tar.gz: ee1b11b2668ee764377741beeac44b50e9507029c1469b5db866f1aa1e61ac93
 SHA512:
-  metadata.gz: 99aa335b527770be65aa661262461ec9b9cc0e1a9f1f2b70153b804b584c5f3de497c0e38f18183d6eac1977d343506d99f42685a49c3bbe3e953781ba3cd176
-  data.tar.gz: 894f7504d9e0f559b79051645f7f2c29de05215de57b2f4e04f78f9eb0bb4145568d13bd593123be401a15f626b9c3872174467dd78920a4ce3f265709bb3712
+  metadata.gz: fe558c786b8286a5f5766c265e1b40b581ef139d05a4b989744ee6d98e1b2dc5d885fc9c1470853d393b23d9c10d99be70c5a1cd7127da6afab653aa0bee21ee
+  data.tar.gz: 89651a0654dcd990829f37e402c9a7b8d214573acf655c54c7460a3708cf7d6d1c8e4f34bdae064fb8b676faa0d02d96fa624d94c8bec492cedc86e967973e86

data/doc/ROADMAP.md

@@ -132,7 +132,8 @@ The planned roadmap ended at V2. Running the gem on real codebases (Patchvault:
 | Emoji + glyph icon detection | ✅ shipped (1.5.0) | `Guardrails::Icons::EmojiScan` catches emoji pictographs and Unicode-dingbat glyphs used as UI iconography — grapheme-cluster iteration (VS16 / ZWJ / flag / keycap count as one), range-first single-codepoint classification, per-file-type comment masking (Prism for Ruby, `<%# %>` for ERB, `//` `/* */` for JS/SCSS, `#` for YAML), `guardrails-ok: emoji` inline marker (first inline-escape convention in the gem), `allow_files` + `allow_chars` config, `SUGGEST=1` sprite-name hints. `guardrails:icons` also flipped to blocking — exit 1 on inline SVGs, unknown sprite refs, or emoji icons. |
 | Lookbook panel on the new data layer | not started | The auto-registered panel still renders from its own `ComponentReport`; it could render `Report::Finding`s and pick up suggestions for free. Icons findings could also flow through — the panel doesn't list icon findings today. |
 | Icons on the new data layer | not started | Icons stays outside `Report::Run` — its rake task calls `Icons.new(root:).run` directly. Migrating gets it into the TUI + HTML report for free but changes the rake shape; hold until there's demand. |
-| CI test workflow | not started | Specs only run inside the release workflow, on one Ruby. A PR-time matrix (3.4 + head) would catch floor regressions before tag time. |
+| Visual-diff adapter registry | ✅ shipped (1.6.0) | `Guardrails::VisualDiff.register_adapter` lets other gems add adapters; the name is checked when the adapter is built. `VisualDiff::Finding` gains `status`, `comment`, `regions`, `extra_details`. First consumer: ui_guardrails-browser's `:browser` adapter. |
+| CI test workflow | ✅ shipped | `.github/workflows/test.yml` runs `bundle exec rspec` (including the `examples/demo` integration spec) and `gem build` on every pull request and push to `main`, on Ruby 3.4 (the floor) and 4.0. Floor regressions and packaging mistakes surface on the PR instead of at tag time. |
 
 ---
 

data/doc/VISUAL-DIFF.md

@@ -61,6 +61,22 @@ With `enabled = true`, `rake guardrails:audit` always runs the visual-diff check
 
 Env always overrides Configuration.
 
+## Adapters from other gems
+
+`Guardrails.configuration.visual_diff.adapter` names a registered adapter. snap_diff is built in; other gems register theirs:
+
+```ruby
+Guardrails::VisualDiff.register_adapter(:browser) do |root:, config:|
+  MyAdapter.new(root: root) # #collect returns Guardrails::VisualDiff::Finding objects
+end
+```
+
+`config` is `Guardrails.configuration.visual_diff`. The name is checked when the adapter is built, so a host initializer can set `adapter = :browser` before the gem that registers it loads. An unregistered name fails with the registered ones listed.
+
+Besides the fields below, adapter findings can set `status` (`"changed"`, `"new"`, ...), `comment`, `regions` (`[{ x:, y:, w:, h: }]`) and `extra_details` (`[[label, value], ...]`). They show up as report details, and a finding with a `status` but no ratio is titled `[changed] scenario`. As with snap_diff, a finding with `mismatch_ratio: nil` always fails.
+
+[ui_guardrails-browser](https://github.com/meticulous/guardrails-browser) registers `:browser`, which reports unresolved items from its own capture and review loop.
+
 ## How the snap_diff adapter works
 
 The snap_diff-capybara gem commits baseline screenshots to git under `doc/screenshots/<name>.png` and, on test failure, writes a sibling `<name>.diff.png` (changed pixels in red) plus a `<name>.heatmap.diff.png` (variance density). Tests fail on baseline mismatches in CI, so the diff files are an artifact of "this regression slipped through to the artifact directory."

data/lib/guardrails/configuration.rb

@@ -44,8 +44,9 @@ module Guardrails
       DEFAULT_ADAPTER       = :snap_diff
       DEFAULT_SNAP_DIFF_DIR = "doc/screenshots"
       DEFAULT_THRESHOLD     = 0.0 # any non-zero mismatch fails
-      KNOWN_ADAPTERS        = %i[snap_diff backstop].freeze
 
+      # `backstop_json` is reserved for the BackstopJS adapter and unused
+      # until it lands; kept so initializers that already set it still load.
       attr_accessor :enabled, :adapter, :snap_diff_dir, :backstop_json, :threshold
 
       def initialize
@@ -56,16 +57,14 @@ module Guardrails
         @threshold     = DEFAULT_THRESHOLD
       end
 
+      # Whether the name is a registered adapter is checked when the
+      # adapter is built (VisualDiff#adapter), not here: an adapter from
+      # another gem may register after this initializer runs.
       def adapter=(value)
         raise ArgumentError, "visual_diff.adapter cannot be nil" if value.nil?
         raise ArgumentError, "visual_diff.adapter cannot be blank" if value.respond_to?(:strip) && value.strip.empty?
 
-        sym = value.to_sym
-        unless KNOWN_ADAPTERS.include?(sym)
-          raise ArgumentError,
-                "Unknown visual_diff adapter #{value.inspect}; expected one of #{KNOWN_ADAPTERS.inspect}"
-        end
-        @adapter = sym
+        @adapter = value.to_sym
       end
 
       def threshold=(value)

data/lib/guardrails/report/finding.rb

@@ -43,9 +43,19 @@ module Guardrails
         {
           category: category, severity: severity, title: title, suggestion: suggestion,
           locations: locations.map(&:to_h), snippet: snippet,
-          details: details.to_h, auto_fix: auto_fix || false
+          details: details_hash, auto_fix: auto_fix || false
         }
       end
+
+      # `details` allows a label more than once (two screenshots, several
+      # regions). A plain `to_h` kept only the last value; a repeated
+      # label collects its values into an array instead. Labels that
+      # appear once stay scalars, so existing JSON doesn't change.
+      def details_hash
+        details.each_with_object({}) do |(label, value), hash|
+          hash[label] = hash.key?(label) ? Array(hash[label]) << value : value
+        end
+      end
     end
 
     # A named group of findings plus the framing paragraph that

data/lib/guardrails/version.rb

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

data/lib/guardrails/visual_diff.rb

@@ -14,7 +14,9 @@ module Guardrails
   #
   # Adapter selection comes from `Guardrails.configuration.visual_diff.adapter`
   # (default `:snap_diff`, the Rails-native baselines-in-git workflow).
-  # BackstopJS support tracked in issue #15.
+  # Other gems add adapters with `VisualDiff.register_adapter`; the
+  # ui_guardrails-browser gem registers `:browser`. BackstopJS support
+  # tracked in issue #15.
   class VisualDiff
     # Normalized across every adapter. Fields adapter-specific shapes
     # don't supply are nil — consumers should not assume presence.
@@ -30,6 +32,10 @@ module Guardrails
       :diff_path,       # relative path to the diff image, nil when no diff exists
       :url,             # optional — set by adapters whose scenarios carry URLs (BackstopJS)
       :selector,        # optional — same
+      :status,          # optional — adapter's review state, e.g. "changed", "new", "rejected"
+      :comment,         # optional — a reviewer's note on the change
+      :regions,         # optional — changed areas, [{ x:, y:, w:, h: }, ...]
+      :extra_details,   # optional — more [label, value] pairs for the report
       keyword_init: true
     ) do
       def to_h
@@ -37,6 +43,34 @@ module Guardrails
       end
     end
 
+    @adapters = {}
+
+    class << self
+      # Adds an adapter under `name`. The block builds it:
+      #
+      #     Guardrails::VisualDiff.register_adapter(:browser) do |root:, config:|
+      #       MyAdapter.new(root: root)
+      #     end
+      #
+      # `config` is `Guardrails.configuration.visual_diff`. The adapter's
+      # `#collect` returns `VisualDiff::Finding`s; a finding with
+      # `mismatch_ratio: nil` always fails, one with a ratio fails above
+      # the threshold.
+      def register_adapter(name, &factory)
+        raise ArgumentError, "register_adapter needs a block that builds the adapter" unless factory
+
+        @adapters[name.to_sym] = factory
+      end
+
+      def adapters
+        @adapters.keys
+      end
+
+      def adapter_factory(name)
+        @adapters[name]
+      end
+    end
+
     def initialize(root:, output: $stdout,
                    adapter: nil, threshold: nil, style: nil)
       @root = Pathname(root)
@@ -82,8 +116,7 @@ module Guardrails
             title: "#{ratio_label(f)} #{f.scenario}#{f.viewport ? " (#{f.viewport})" : ""}",
             suggestion: SUGGESTION,
             locations: [f.diff_path, f.baseline_path].compact.map { |path| Report::Location.new(file: path) },
-            details: [["baseline", f.baseline_path], ["diff", f.diff_path], ["url", f.url], ["selector", f.selector]]
-                     .reject { |_, v| v.nil? }
+            details: details_for(f)
           )
         }
       )]
@@ -100,19 +133,27 @@ module Guardrails
     SUGGESTION = "compare baseline ↔ diff; accept the new baseline or fix the regression"
 
     def ratio_label(finding)
-      finding.mismatch_ratio.nil? ? "[diff present]" : "[#{(finding.mismatch_ratio * 100).round(2)}% mismatch]"
+      return "[#{(finding.mismatch_ratio * 100).round(2)}% mismatch]" unless finding.mismatch_ratio.nil?
+
+      finding.status ? "[#{finding.status}]" : "[diff present]"
+    end
+
+    def details_for(finding)
+      regions = finding.regions&.map { |r| "#{r[:x] || r["x"]},#{r[:y] || r["y"]} #{r[:w] || r["w"]}x#{r[:h] || r["h"]}" }
+      [["baseline", finding.baseline_path], ["current", finding.current_path], ["diff", finding.diff_path],
+       ["url", finding.url], ["selector", finding.selector], ["status", finding.status],
+       ["comment", finding.comment], ["regions", regions&.join("; ")]]
+        .reject { |_, v| v.nil? || v == "" } + Array(finding.extra_details)
     end
 
     def adapter
-      case @adapter_name
-      when :snap_diff
-        SnapDiff.new(
-          root: @root,
-          dir: Guardrails.configuration.visual_diff.snap_diff_dir
-        )
-      else
-        raise ArgumentError, "Unknown visual_diff adapter: #{@adapter_name.inspect}"
+      factory = self.class.adapter_factory(@adapter_name)
+      unless factory
+        raise ArgumentError,
+              "Unknown visual_diff adapter: #{@adapter_name.inspect}; registered: #{self.class.adapters.inspect}"
       end
+
+      factory.call(root: @root, config: Guardrails.configuration.visual_diff)
     end
 
     def coerce_adapter(value)
@@ -149,9 +190,14 @@ module Guardrails
         @output.puts "    #{@style.location("diff:     #{f.diff_path}")}" if f.diff_path
         @output.puts "    #{@style.location("url:      #{f.url}")}" if f.url
         @output.puts "    #{@style.location("selector: #{f.selector}")}" if f.selector
+        @output.puts "    #{@style.location("comment:  #{f.comment}")}" if f.comment
       end
     end
   end
 end
 
 require_relative "visual_diff/snap_diff"
+
+Guardrails::VisualDiff.register_adapter(:snap_diff) do |root:, config:|
+  Guardrails::VisualDiff::SnapDiff.new(root: root, dir: config.snap_diff_dir)
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - John Athayde