ui_guardrails 1.0.0

data/lib/guardrails/visual_diff.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "configuration"
+
+module Guardrails
+  # Consumes screenshot-diff tool output and folds findings into the
+  # unified audit report. Same playbook as `A11yDeep` for axe — parser
+  # only, no Capybara / Chromium / Playwright runtime deps. Users keep
+  # their existing visual-regression toolchain; Guardrails provides the
+  # merge + report + exit-code contract.
+  #
+  # 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.
+  class VisualDiff
+    # Normalized across every adapter. Fields adapter-specific shapes
+    # don't supply are nil — consumers should not assume presence.
+    #
+    # Defined before the adapter requires so the constant exists by the
+    # time `lib/guardrails/visual_diff/snap_diff.rb` loads.
+    Finding = Struct.new(
+      :scenario,        # human label, e.g. "checkout/cart" or "homepage_desktop"
+      :viewport,        # "desktop" / "mobile" / nil if not applicable
+      :mismatch_ratio,  # 0.0..1.0 when the adapter emits one; nil for boolean adapters (snap_diff)
+      :baseline_path,   # relative path to the reference image
+      :current_path,    # relative path to the actual screenshot
+      :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
+      keyword_init: true
+    ) do
+      def to_h
+        super
+      end
+    end
+
+    def initialize(root:, output: $stdout,
+                   adapter: nil, threshold: nil)
+      @root = Pathname(root)
+      @output = output
+      cfg = Guardrails.configuration.visual_diff
+      # Coerce constructor inputs the same way Configuration setters
+      # do, so `VisualDiff.new(adapter: "snap_diff", threshold: "0.1")`
+      # works the same as `Guardrails.configure { |c| c.visual_diff.
+      # adapter = "snap_diff"; c.visual_diff.threshold = "0.1" }`.
+      @adapter_name = coerce_adapter(adapter) || cfg.adapter
+      @threshold = threshold.nil? ? cfg.threshold : Float(threshold)
+    end
+
+    def run
+      findings = collect
+      print_report(findings)
+      findings
+    end
+
+    # Returns true when any finding's mismatch_ratio exceeds the
+    # threshold. Adapters that don't emit a ratio (snap_diff: presence
+    # of a .diff.png is binary) report nil, which we treat as
+    # "unconditional fail" — those findings always fail.
+    def any_failing?(findings)
+      findings.any? { |f| failing?(f) }
+    end
+
+    def collect
+      adapter.collect
+    end
+
+    private
+
+    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}"
+      end
+    end
+
+    def coerce_adapter(value)
+      return nil if value.nil?
+
+      value.to_sym
+    end
+
+    def failing?(finding)
+      ratio = finding.mismatch_ratio
+      return true if ratio.nil?
+
+      ratio > @threshold
+    end
+
+    def print_report(findings)
+      return if findings.empty?
+
+      @output.puts ""
+      @output.puts "Guardrails visual diff: #{findings.length} finding#{'s' if findings.length != 1} " \
+                   "(adapter: #{@adapter_name}, threshold: #{@threshold})"
+
+      findings.each do |f|
+        ratio_label = f.mismatch_ratio.nil? ? "[diff present]" : "[#{(f.mismatch_ratio * 100).round(2)}% mismatch]"
+        suffix = f.viewport ? " (#{f.viewport})" : ""
+        @output.puts ""
+        @output.puts "  #{ratio_label} #{f.scenario}#{suffix}"
+        @output.puts "    baseline: #{f.baseline_path}" if f.baseline_path
+        @output.puts "    diff:     #{f.diff_path}" if f.diff_path
+        @output.puts "    url:      #{f.url}" if f.url
+        @output.puts "    selector: #{f.selector}" if f.selector
+      end
+    end
+  end
+end
+
+require_relative "visual_diff/snap_diff"

data/lib/guardrails.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "guardrails/version"
+# Configuration carries the `Guardrails.configure { |c| ... }` block
+# users place in `config/initializers/guardrails.rb`. Loaded eagerly
+# at `require "guardrails"` time so the initializer doesn't NoMethodError
+# on first use — caught by the local-build verification of 1.0.0
+# before the third publish attempt.
+require_relative "guardrails/configuration"
+require_relative "guardrails/railtie" if defined?(Rails::Railtie)
+
+module Guardrails
+  class Error < StandardError; end
+end

data/lib/tasks/guardrails.rake

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+namespace :guardrails do
+  desc "Initialize Guardrails configuration and analyze stylesheet stack (FORCE=1 to overwrite existing config)"
+  task :init do
+    require "guardrails/init"
+    root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+    force = %w[1 true yes].include?(ENV["FORCE"]&.downcase)
+    Guardrails::Init.new(root: root, force: force).run
+  end
+
+  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json)"
+  task :audit do
+    require "guardrails/audit"
+    require "guardrails/stimulus_audit"
+    require "guardrails/partial_similarity"
+    require "guardrails/view_component_audit"
+    require "guardrails/a11y_audit"
+    require "guardrails/cross_codebase_patterns"
+    require "guardrails/class_itis"
+    require "guardrails/a11y_deep"
+    require "guardrails/visual_diff"
+    require "stringio"
+    root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+    axe_json_path = ENV["AXE_JSON"]
+
+    # Visual-diff is opt-in (baselines need deliberate setup). Enabled
+    # when either VISUAL_DIFF=1 is set in the env (sidecar mode) or
+    # Guardrails.configuration.visual_diff.enabled was flipped on by a
+    # Rails initializer (embedded mode). Env overrides Configuration.
+    visual_diff_env = %w[1 true yes].include?(ENV["VISUAL_DIFF"]&.downcase)
+    visual_diff_on = visual_diff_env || Guardrails.configuration.visual_diff.enabled
+    # Strip + reject blank env values — an empty VISUAL_DIFF_DIR would
+    # otherwise be applied as snap_diff_dir = "" and glob from the repo
+    # root (potentially scanning the whole tree).
+    if (dir = ENV["VISUAL_DIFF_DIR"]) && !dir.strip.empty?
+      Guardrails.configure { |c| c.visual_diff.snap_diff_dir = dir.strip }
+    end
+    if (thr = ENV["VISUAL_DIFF_THRESHOLD"]) && !thr.strip.empty?
+      Guardrails.configure { |c| c.visual_diff.threshold = thr.strip }
+    end
+    suggest = %w[1 true yes].include?(ENV["SUGGEST"]&.downcase)
+    apply = %w[1 true yes].include?(ENV["APPLY"]&.downcase)
+    format = ENV["FORMAT"]&.downcase == "json" ? :json : :text
+    similarity_opts = { root: root }
+    similarity_opts[:threshold] = ENV["SIMILARITY_THRESHOLD"].to_f if ENV["SIMILARITY_THRESHOLD"]
+    pattern_opts = { root: root }
+    pattern_opts[:min_size] = ENV["PATTERN_MIN_SIZE"].to_i if ENV["PATTERN_MIN_SIZE"]
+    pattern_opts[:min_occurrences] = ENV["PATTERN_MIN_OCCURRENCES"].to_i if ENV["PATTERN_MIN_OCCURRENCES"]
+    classitis_opts = { root: root }
+    classitis_opts[:min_classes] = ENV["CLASSITIS_MIN_CLASSES"].to_i if ENV["CLASSITIS_MIN_CLASSES"]
+    classitis_opts[:min_occurrences] = ENV["CLASSITIS_MIN_OCCURRENCES"].to_i if ENV["CLASSITIS_MIN_OCCURRENCES"]
+
+    if format == :json
+      # Run sub-audits silently so the only thing printed to stdout is one
+      # JSON document. Audit's own JSON output goes through @output, so we
+      # capture it instead of re-emitting.
+      sink = StringIO.new
+      violations = Guardrails::Audit.new(
+        root: root, output: sink, suggest: suggest, apply: apply, format: :text
+      ).run
+      stimulus = Guardrails::StimulusAudit.new(root: root, output: sink).run
+      similarity_opts[:output] = sink
+      similarity = Guardrails::PartialSimilarity.new(**similarity_opts).run
+      vc = Guardrails::ViewComponentAudit.new(root: root, output: sink).run
+      a11y = Guardrails::A11yAudit.new(root: root, output: sink).run
+      pattern_opts[:output] = sink
+      patterns = Guardrails::CrossCodebasePatterns.new(**pattern_opts).run
+      classitis_opts[:output] = sink
+      classitis = Guardrails::ClassItis.new(**classitis_opts).run
+      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path, output: sink) : nil
+      a11y_deep = a11y_deep_runner&.run || []
+      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root, output: sink) : nil
+      visual_diff = visual_diff_runner&.run || []
+
+      require "json"
+      payload = {
+        summary: {
+          violations: violations.length,
+          stimulus_orphaned: stimulus.orphaned.length,
+          stimulus_dead: stimulus.dead.length,
+          similar_partials: similarity.length,
+          missing_previews: vc.missing_previews.length,
+          orphan_slots: vc.orphan_slots.length,
+          a11y: a11y.length,
+          a11y_deep: a11y_deep.length,
+          patterns: patterns.length,
+          classitis: classitis.length,
+          visual_diff: visual_diff.length
+        },
+        violations: violations.map(&:to_h),
+        stimulus: { orphaned: stimulus.orphaned, dead: stimulus.dead },
+        similar_partials: similarity.map(&:to_h),
+        view_components: {
+          missing_previews: vc.missing_previews,
+          orphan_slots: vc.orphan_slots.map(&:to_h)
+        },
+        a11y: a11y.map(&:to_h),
+        a11y_deep: a11y_deep.map(&:to_h),
+        patterns: patterns.map { |p|
+          { fingerprint: p.fingerprint, shape: p.shape, size: p.size, count: p.count, occurrences: p.occurrences.map(&:to_h) }
+        },
+        classitis: classitis.map { |c|
+          { tag: c.tag, classes: c.classes, count: c.count, occurrences: c.occurrences.map(&:to_h) }
+        },
+        visual_diff: visual_diff.map(&:to_h)
+      }
+      $stdout.puts JSON.pretty_generate(payload)
+    else
+      violations = Guardrails::Audit.new(
+        root: root, suggest: suggest, apply: apply, format: :text
+      ).run
+      stimulus = Guardrails::StimulusAudit.new(root: root).run
+      similarity = Guardrails::PartialSimilarity.new(**similarity_opts).run
+      vc = Guardrails::ViewComponentAudit.new(root: root).run
+      a11y = Guardrails::A11yAudit.new(root: root).run
+      patterns = Guardrails::CrossCodebasePatterns.new(**pattern_opts).run
+      classitis = Guardrails::ClassItis.new(**classitis_opts).run
+      a11y_deep_runner = axe_json_path ? Guardrails::A11yDeep.new(input: axe_json_path) : nil
+      a11y_deep = a11y_deep_runner&.run || []
+      visual_diff_runner = visual_diff_on ? Guardrails::VisualDiff.new(root: root) : nil
+      visual_diff = visual_diff_runner&.run || []
+    end
+
+    # Deep a11y findings only fail the audit when their impact crosses
+    # the configured threshold (default: any impact fails, same as
+    # static a11y). When AXE_JSON is not set, a11y_deep is [] and the
+    # check is a no-op. Same logic for visual_diff: opt-in via
+    # VISUAL_DIFF=1 / Configuration; threshold gates failure.
+    a11y_deep_failing = a11y_deep_runner&.any_failing?(a11y_deep) || false
+    visual_diff_failing = visual_diff_runner&.any_failing?(visual_diff) || false
+    exit 1 if violations.any? || stimulus.violations? || similarity.any? || vc.violations? || a11y.any? || a11y_deep_failing || visual_diff_failing
+  end
+
+  desc "Parse axe-core JSON output and report deep a11y findings (AXE_JSON=path/to/axe.json)"
+  task :"a11y:deep" do
+    require "guardrails/a11y_deep"
+    path = ENV["AXE_JSON"] or abort "Set AXE_JSON=path/to/axe.json (output from `npx @axe-core/cli ... --save`)"
+    runner = Guardrails::A11yDeep.new(input: path)
+    findings = runner.run
+    exit 1 if runner.any_failing?(findings)
+  end
+
+  desc "Consume screenshot-diff output and report visual regressions (VISUAL_DIFF_DIR=..., VISUAL_DIFF_THRESHOLD=0.0)"
+  task :"visual:deep" do
+    require "guardrails/visual_diff"
+    root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+    # The standalone task implies the user is opting in regardless of
+    # Configuration; flip enabled on so a no-config sidecar run works.
+    Guardrails.configure { |c| c.visual_diff.enabled = true }
+    # Same blank-env guard as the main audit task — see note there.
+    if (dir = ENV["VISUAL_DIFF_DIR"]) && !dir.strip.empty?
+      Guardrails.configure { |c| c.visual_diff.snap_diff_dir = dir.strip }
+    end
+    if (thr = ENV["VISUAL_DIFF_THRESHOLD"]) && !thr.strip.empty?
+      Guardrails.configure { |c| c.visual_diff.threshold = thr.strip }
+    end
+    runner = Guardrails::VisualDiff.new(root: root)
+    findings = runner.run
+    exit 1 if runner.any_failing?(findings)
+  end
+
+  desc "Generate SVG icon sprite and audit icon usage"
+  task :icons do
+    require "guardrails/icons"
+    root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+    Guardrails::Icons.new(root: root).run
+  end
+
+  desc "Audit design tokens and report drift"
+  task :tokens do
+    require "guardrails/tokens"
+    root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
+    Guardrails::Tokens.new(root: root).run
+  end
+end

data/lib/ui_guardrails.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Shim so that `gem "ui_guardrails"` in a Gemfile and the
+# default Bundler/Rails auto-require pattern (`require "meticulous_
+# guardrails"`) reach the canonical entry point at lib/guardrails.rb.
+# The Ruby module is `Guardrails`; only the gem package name on
+# rubygems.org is namespaced under the org. See the CHANGELOG entry
+# for 1.0.0 for the rename rationale.
+require_relative "guardrails"

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: ui_guardrails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- John Athayde
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: herb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: 'Opinionated auditing and enforcement for design-system consistency:
+  component inventory, icon sprites, type scale, and color token management.'
+email:
+- jmpa@meticulous.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- doc/A11Y.md
+- doc/LOOKBOOK.md
+- doc/PRD.md
+- doc/PUBLISHING.md
+- doc/ROADMAP.md
+- doc/UPSTREAM-snap_diff-issue-draft.md
+- doc/VISUAL-DIFF.md
+- lib/guardrails.rb
+- lib/guardrails/a11y_audit.rb
+- lib/guardrails/a11y_deep.rb
+- lib/guardrails/audit.rb
+- lib/guardrails/audit/auto_fixer.rb
+- lib/guardrails/audit/markdown_writer.rb
+- lib/guardrails/class_itis.rb
+- lib/guardrails/configuration.rb
+- lib/guardrails/cross_codebase_patterns.rb
+- lib/guardrails/erb_parser.rb
+- lib/guardrails/hex_normalizer.rb
+- lib/guardrails/icons.rb
+- lib/guardrails/init.rb
+- lib/guardrails/init/config_writer.rb
+- lib/guardrails/init/media_query_scaffolder.rb
+- lib/guardrails/init/prompter.rb
+- lib/guardrails/init/stack_detector.rb
+- lib/guardrails/lookbook/component_report.rb
+- lib/guardrails/lookbook/panel_registration.rb
+- lib/guardrails/lookbook/views/lookbook_panels/_guardrails.html.erb
+- lib/guardrails/partial_similarity.rb
+- lib/guardrails/railtie.rb
+- lib/guardrails/stimulus_audit.rb
+- lib/guardrails/token_matcher.rb
+- lib/guardrails/tokens.rb
+- lib/guardrails/tokens/tailwind_config_parser.rb
+- lib/guardrails/version.rb
+- lib/guardrails/view_component_audit.rb
+- lib/guardrails/visual_diff.rb
+- lib/guardrails/visual_diff/snap_diff.rb
+- lib/tasks/guardrails.rake
+- lib/ui_guardrails.rb
+homepage: https://github.com/meticulous/guardrails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/meticulous/guardrails
+  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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Rails toolset for preventing UI drift in AI-assisted applications.
+test_files: []