ui_guardrails 1.0.0

data/lib/guardrails/class_itis.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "erb_parser"
+
+module Guardrails
+  # Finds repeating "class soup" — the same long class list applied to
+  # the same tag in many places. The classic AI-assisted-Rails failure
+  # mode: a 6-utility `class="px-4 py-2 text-sm font-medium bg-white
+  # rounded-md"` ends up copy-pasted onto 30 buttons because the
+  # assistant doesn't know the codebase already has a `ButtonComponent`
+  # or `.btn-base` class.
+  #
+  # Distinct from CrossCodebasePatterns (structural shape, ignores
+  # classes) and PartialSimilarity (whole-partial Jaccard). This audit
+  # looks at *single elements* whose class attribute is a repeated
+  # high-cardinality literal — the cleanest signal for "extract a
+  # ButtonComponent / use @apply / add a semantic class."
+  class ClassItis
+    Occurrence = Struct.new(:file, :line, :column, keyword_init: true)
+
+    Cluster = Struct.new(:tag, :classes, :occurrences, keyword_init: true) do
+      def count
+        occurrences.length
+      end
+
+      def class_count
+        classes.length
+      end
+    end
+
+    # Below this many tokens in the class list, repetition is fine —
+    # `<button class="primary">` everywhere is intentional, not soup.
+    # Soup starts when 5+ classes pile up on one element with no
+    # semantic name to anchor them.
+    DEFAULT_MIN_CLASSES = 5
+
+    # Same threshold as CrossCodebasePatterns — 2 occurrences are noise,
+    # 3+ implies a real recurring pattern worth extracting.
+    DEFAULT_MIN_OCCURRENCES = 3
+
+    DEFAULT_MAX_OCCURRENCES_SHOWN = 10
+
+    VIEW_PATTERNS = [
+      "app/views/**/*.html.erb",
+      "app/components/**/*.html.erb"
+    ].freeze
+
+    IMPLICIT_IGNORE_SEGMENTS = %w[vendor node_modules tmp public log].freeze
+    IMPLICIT_IGNORE_PATTERNS = [/\A(?:\w+_)?mailer\z/].freeze
+
+    def initialize(root:, output: $stdout,
+                   min_classes: DEFAULT_MIN_CLASSES,
+                   min_occurrences: DEFAULT_MIN_OCCURRENCES,
+                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN)
+      @root = Pathname(root)
+      @output = output
+      @min_classes = min_classes
+      @min_occurrences = min_occurrences
+      @max_occurrences_shown = max_occurrences_shown
+    end
+
+    def run
+      clusters = find_clusters
+      print_report(clusters)
+      clusters
+    end
+
+    def find_clusters
+      groups = Hash.new { |h, k| h[k] = [] }
+
+      view_files.each do |file|
+        content = File.read(file, encoding: Encoding::UTF_8)
+        result = ErbParser.parse(content)
+        relative = file.relative_path_from(@root).to_s
+
+        ErbParser.each_node(result.document) do |node|
+          next unless node.is_a?(::Herb::AST::HTMLElementNode)
+
+          tag = element_tag_name(node)
+          next if tag.nil?
+
+          classes = static_class_tokens(node)
+          next if classes.length < @min_classes
+
+          line, column = ErbParser.start_position(node)
+          key = [tag, classes]
+          groups[key] << Occurrence.new(file: relative, line: line, column: column)
+        end
+      end
+
+      groups
+        .select { |_, occs| occs.length >= @min_occurrences }
+        .map { |(tag, classes), occs| Cluster.new(tag: tag, classes: classes, occurrences: occs) }
+        .sort_by { |c| [-c.count, -c.class_count] }
+    end
+
+    private
+
+    def view_files
+      paths = VIEW_PATTERNS.flat_map { |g| Dir.glob(@root.join(g)) }.map { |p| Pathname(p) }.uniq
+      paths.reject { |p| ignored?(p) }
+    end
+
+    def ignored?(path)
+      segments = path.relative_path_from(@root).to_s.split("/")
+      return true if (IMPLICIT_IGNORE_SEGMENTS & segments).any?
+
+      segments.any? { |seg| IMPLICIT_IGNORE_PATTERNS.any? { |pat| seg.match?(pat) } }
+    end
+
+    def element_tag_name(element)
+      return nil unless element.respond_to?(:open_tag) && element.open_tag
+
+      tok = element.open_tag.tag_name
+      tok && tok.respond_to?(:value) ? tok.value.to_s.downcase : nil
+    end
+
+    # Pull the static portion of the element's `class` attribute. If
+    # the attribute is missing, ERB-driven, or empty, returns []. ERB
+    # fragments inside a class attribute are dropped (we can't know
+    # what they'll render); the literal pieces are concatenated and
+    # whitespace-tokenized. Tokens are sorted so two identical lists
+    # in different source order produce the same fingerprint key.
+    def static_class_tokens(element)
+      attr = class_attribute_node(element)
+      return [] unless attr
+
+      static = static_attribute_value(attr)
+      return [] if static.nil? || static.strip.empty?
+
+      static.split(/\s+/).reject(&:empty?).sort.uniq
+    end
+
+    def class_attribute_node(element)
+      open_children = ErbParser.compact_children(element.open_tag)
+      open_children.find do |child|
+        next false unless child.is_a?(::Herb::AST::HTMLAttributeNode)
+
+        name_wrapper, _value_wrapper = ErbParser.compact_children(child)
+        next false unless name_wrapper
+
+        literal = ErbParser.compact_children(name_wrapper).first
+        next false unless literal && literal.respond_to?(:content)
+
+        name = literal.content.respond_to?(:value) ? literal.content.value.to_s : literal.content.to_s
+        name.downcase == "class"
+      end
+    end
+
+    def static_attribute_value(attribute_node)
+      _name_wrapper, value_wrapper = ErbParser.compact_children(attribute_node)
+      return nil unless value_wrapper
+
+      ErbParser.compact_children(value_wrapper).filter_map do |child|
+        next unless child.is_a?(::Herb::AST::LiteralNode)
+
+        content = child.content
+        content.respond_to?(:value) ? content.value.to_s : content.to_s
+      end.join
+    end
+
+    def print_report(clusters)
+      return if clusters.empty?
+
+      total_occurrences = clusters.sum(&:count)
+      noun = clusters.length == 1 ? "cluster" : "clusters"
+      @output.puts ""
+      @output.puts "Guardrails class-itis: #{clusters.length} repeating class #{noun} " \
+                   "(#{total_occurrences} occurrences; >= #{@min_classes} classes, >= #{@min_occurrences} occurrences)"
+
+      clusters.each do |cluster|
+        @output.puts ""
+        @output.puts "  <#{cluster.tag}> with #{cluster.class_count} classes, " \
+                     "#{cluster.count} occurrences:"
+        @output.puts "    class=#{format_classes(cluster.classes)}"
+        cluster.occurrences.first(@max_occurrences_shown).each do |occ|
+          @output.puts "    #{occ.file}:#{occ.line}"
+        end
+        if cluster.occurrences.length > @max_occurrences_shown
+          remaining = cluster.occurrences.length - @max_occurrences_shown
+          @output.puts "    … and #{remaining} more"
+        end
+      end
+    end
+
+    # Cap the displayed class string so a 30-utility soup doesn't blow
+    # out the terminal. Fingerprint matching is on the full sorted list,
+    # so display truncation is purely cosmetic.
+    def format_classes(classes, limit: 100)
+      joined = classes.join(" ")
+      str = joined.length <= limit ? joined : "#{joined[0, limit - 3]}..."
+      "\"#{str}\""
+    end
+  end
+end

data/lib/guardrails/configuration.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Guardrails
+  # Ruby-level configuration object, intended for `config/initializers/
+  # guardrails.rb` in embedded (in-Gemfile) installs:
+  #
+  #     Guardrails.configure do |c|
+  #       c.visual_diff.enabled    = true
+  #       c.visual_diff.threshold  = 0.02   # tolerate up to 2% mismatch
+  #       c.visual_diff.snap_diff_dir = "spec/screenshots"
+  #     end
+  #
+  # Precedence for the `visual_diff` section (highest → lowest):
+  #
+  #   1. Environment variables (`VISUAL_DIFF=1`, `VISUAL_DIFF_DIR=…`,
+  #      `VISUAL_DIFF_THRESHOLD=…` — same env vars sidecar-mode users
+  #      already rely on)
+  #   2. `Guardrails.configure` block (embedded-mode initializer)
+  #   3. Built-in defaults (`enabled: false`, `adapter: :snap_diff`,
+  #      `snap_diff_dir: "doc/screenshots"`, `threshold: 0.0`)
+  #
+  # `guardrails.yml` does NOT participate in this object's precedence
+  # yet — that's how existing detectors (Audit, Tokens, etc.) read
+  # their config, and migrating them onto `Guardrails::Configuration`
+  # is a separate refactor not in 0.8.0 scope.
+  #
+  # In 0.8.0 the only section is `visual_diff`. Existing detectors
+  # continue using their constructor-injected configuration + yml
+  # access pattern.
+  class Configuration
+    attr_reader :visual_diff
+
+    def initialize
+      @visual_diff = VisualDiffConfig.new
+    end
+
+    # Nested configuration for the visual-diff audit. Adapter selection
+    # determines which screenshot-tool output we ingest; per-adapter
+    # paths and a global threshold round it out.
+    class VisualDiffConfig
+      # Built-in defaults — kept here, not in env-var fallback logic,
+      # so a user reading the Configuration class can see "what does
+      # Guardrails ship with" without grepping rake tasks.
+      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
+
+      attr_accessor :enabled, :adapter, :snap_diff_dir, :backstop_json, :threshold
+
+      def initialize
+        @enabled       = false # opt-in: visual baselines need deliberate setup
+        @adapter       = DEFAULT_ADAPTER
+        @snap_diff_dir = DEFAULT_SNAP_DIFF_DIR
+        @backstop_json = nil
+        @threshold     = DEFAULT_THRESHOLD
+      end
+
+      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
+      end
+
+      def threshold=(value)
+        raise ArgumentError, "visual_diff.threshold cannot be nil" if value.nil?
+        raise ArgumentError, "visual_diff.threshold cannot be blank" if value.respond_to?(:strip) && value.strip.empty?
+
+        float = Float(value)
+        unless float >= 0.0 && float <= 1.0
+          raise ArgumentError,
+                "visual_diff.threshold must be between 0.0 and 1.0; got #{value.inspect}"
+        end
+        @threshold = float
+      end
+    end
+  end
+
+  class << self
+    # Cached Configuration singleton. Tests can reset via
+    # `Guardrails.reset_configuration!` so changes in one example
+    # don't leak into another.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/guardrails/cross_codebase_patterns.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "digest"
+require "set"
+require_relative "erb_parser"
+
+module Guardrails
+  # Finds recurring structural patterns across the codebase — element
+  # subtrees that appear in 3+ places and could be extracted into a
+  # shared partial or ViewComponent.
+  #
+  # Distinct from PartialSimilarity: that one compares EXISTING partials
+  # against each other ("are these two partials near-duplicates?").
+  # CrossCodebasePatterns looks at the structural shape of any subtree
+  # in any view ("this 8-element shape appears in 12 places, only one
+  # of which is a partial — refactor candidate").
+  class CrossCodebasePatterns
+    Occurrence = Struct.new(:file, :line, :column, :size, keyword_init: true)
+
+    Pattern = Struct.new(:fingerprint, :shape, :size, :occurrences, keyword_init: true) do
+      def count
+        occurrences.length
+      end
+    end
+
+    # Minimum number of element nodes in a subtree before we consider it.
+    # Below this, the structural shape is too generic to be a refactor
+    # candidate — `<div>` alone, or `<span><a></a></span>`, would match
+    # constantly. A useful pattern starts around 5 elements (card body,
+    # form row, table cell with controls, etc.).
+    DEFAULT_MIN_SIZE = 5
+
+    # Subtree fingerprint must appear at least this many times to surface.
+    # 2 occurrences are common and rarely actionable; 3+ implies a real
+    # repeated shape.
+    DEFAULT_MIN_OCCURRENCES = 3
+
+    # Max occurrences printed per pattern before we elide the rest.
+    DEFAULT_MAX_OCCURRENCES_SHOWN = 10
+
+    VIEW_PATTERNS = [
+      "app/views/**/*.html.erb",
+      "app/components/**/*.html.erb"
+    ].freeze
+
+    IMPLICIT_IGNORE_SEGMENTS = %w[vendor node_modules tmp public log].freeze
+    IMPLICIT_IGNORE_PATTERNS = [/\A(?:\w+_)?mailer\z/].freeze
+
+    def initialize(root:, output: $stdout,
+                   min_size: DEFAULT_MIN_SIZE,
+                   min_occurrences: DEFAULT_MIN_OCCURRENCES,
+                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN)
+      @root = Pathname(root)
+      @output = output
+      @min_size = min_size
+      @min_occurrences = min_occurrences
+      @max_occurrences_shown = max_occurrences_shown
+    end
+
+    def run
+      patterns = find_patterns
+      print_report(patterns)
+      patterns
+    end
+
+    def find_patterns
+      occurrences = Hash.new { |h, k| h[k] = [] }
+      shapes = {}
+
+      view_files.each do |file|
+        content = File.read(file, encoding: Encoding::UTF_8)
+        result = ErbParser.parse(content)
+        relative = file.relative_path_from(@root).to_s
+
+        walk_subtrees(result.document) do |node, fingerprint, shape, size|
+          next if size < @min_size
+
+          line, column = ErbParser.start_position(node)
+          occurrences[fingerprint] << Occurrence.new(
+            file: relative,
+            line: line,
+            column: column,
+            size: size
+          )
+          shapes[fingerprint] ||= shape
+        end
+      end
+
+      patterns = occurrences
+                 .select { |_, occs| occs.size >= @min_occurrences }
+                 .map { |fp, occs| Pattern.new(fingerprint: fp, shape: shapes[fp], size: occs.first.size, occurrences: occs) }
+                 .sort_by { |p| [-p.count, -p.size] }
+
+      dedupe_nested(patterns)
+    end
+
+    private
+
+    # Drop redundant inner shapes. When a table repeats N times, three
+    # patterns end up with identical counts:
+    #
+    #   table(thead(tr(th,th,th)),tbody)   8x
+    #   thead(tr(th,th,th))                 8x
+    #   tr(th,th,th)                        8x
+    #
+    # The outer pattern is the one a refactor would extract; the inner
+    # shapes are just nested views of the same locations. Drop pattern A
+    # if there's another pattern B such that:
+    #   - A's shape appears as a sub-shape inside B's shape, AND
+    #   - A.count == B.count, AND
+    #   - every file in A.occurrences is also in B.occurrences
+    #
+    # Equal-count + file-containment is a strong signal that A's
+    # occurrences are exactly the children of B's occurrences — not a
+    # distinct repeated structure.
+    def dedupe_nested(patterns)
+      patterns.reject do |inner|
+        patterns.any? do |outer|
+          next false if outer.equal?(inner)
+          next false unless outer.count == inner.count
+          next false unless outer.size > inner.size
+          next false unless contains_subshape?(outer.shape, inner.shape)
+
+          outer_files = outer.occurrences.map(&:file).to_set
+          inner.occurrences.all? { |o| outer_files.include?(o.file) }
+        end
+      end
+    end
+
+    # True if `outer` contains `inner` as a proper child sub-shape — i.e.
+    # `inner` appears inside `outer` bounded by `(` / `,` on the left and
+    # `)` / `,` on the right. The left bound must be a real `(` or `,`,
+    # never the start of the string: a prefix match like inner=`div(a)`
+    # against outer=`div(a,a)` would otherwise look valid (before=nil,
+    # after=`,`) even though it represents a structurally different
+    # subtree (1 child vs 2), causing dedupe_nested to drop a legitimate
+    # distinct pattern.
+    def contains_subshape?(outer, inner)
+      idx = 1 # i > 0 only — never accept a prefix match
+      while (i = outer.index(inner, idx))
+        before = outer[i - 1]
+        after = outer[i + inner.length]
+        return true if ["(", ","].include?(before) && [")", ","].include?(after)
+
+        idx = i + 1
+      end
+      false
+    end
+
+    def view_files
+      paths = VIEW_PATTERNS.flat_map { |g| Dir.glob(@root.join(g)) }.map { |p| Pathname(p) }.uniq
+      paths.reject { |p| ignored?(p) }
+    end
+
+    def ignored?(path)
+      segments = path.relative_path_from(@root).to_s.split("/")
+      return true if (IMPLICIT_IGNORE_SEGMENTS & segments).any?
+
+      segments.any? { |seg| IMPLICIT_IGNORE_PATTERNS.any? { |pat| seg.match?(pat) } }
+    end
+
+    # Walk the document yielding every HTMLElementNode subtree with its
+    # computed fingerprint. Recurses into element bodies so nested
+    # subtrees are reported alongside their parents.
+    def walk_subtrees(node, &block)
+      if node.is_a?(::Herb::AST::HTMLElementNode)
+        fingerprint, shape, size = compute_subtree(node)
+        yield node, fingerprint, shape, size if fingerprint
+
+        Array(node.body).each { |child| walk_subtrees(child, &block) }
+      else
+        # DocumentNode and other non-element wrappers — descend into
+        # children but don't yield for them.
+        ErbParser.compact_children(node).each { |child| walk_subtrees(child, &block) }
+      end
+    end
+
+    # Build a recursive shape string for an element subtree.
+    #
+    #   <div><h2>x</h2><p>y</p></div>  →  shape "div(h2,p)", size 3
+    #
+    # Returns [fingerprint, shape, size] — fingerprint is a short SHA
+    # hash of the shape (cheap to compare, bounded memory). Size counts
+    # element nodes; text and ERB don't contribute.
+    def compute_subtree(node)
+      return [nil, "", 0] unless node.is_a?(::Herb::AST::HTMLElementNode)
+
+      tag = element_tag_name(node)
+      return [nil, "", 0] if tag.nil?
+
+      child_results = Array(node.body)
+                      .map { |c| compute_subtree(c) }
+                      .reject { |fp, _, _| fp.nil? }
+      child_shapes = child_results.map { |_, sh, _| sh }
+      child_size = child_results.sum { |_, _, sz| sz }
+
+      shape = child_shapes.empty? ? tag : "#{tag}(#{child_shapes.join(',')})"
+      fingerprint = Digest::SHA256.hexdigest(shape)[0, 16]
+
+      [fingerprint, shape, child_size + 1]
+    end
+
+    def element_tag_name(element)
+      return nil unless element.respond_to?(:open_tag) && element.open_tag
+
+      tok = element.open_tag.tag_name
+      tok && tok.respond_to?(:value) ? tok.value.to_s.downcase : nil
+    end
+
+    def print_report(patterns)
+      return if patterns.empty?
+
+      total_occurrences = patterns.sum(&:count)
+      noun = patterns.length == 1 ? "shape" : "shapes"
+      @output.puts ""
+      @output.puts "Guardrails patterns: #{patterns.length} recurring #{noun} " \
+                   "(#{total_occurrences} occurrences; >= #{@min_size} elements, >= #{@min_occurrences} occurrences)"
+
+      patterns.each do |pattern|
+        @output.puts ""
+        @output.puts "  Pattern (#{pattern.size} elements, #{pattern.count} occurrences): #{truncate_shape(pattern.shape)}"
+        pattern.occurrences.first(@max_occurrences_shown).each do |occ|
+          @output.puts "    #{occ.file}:#{occ.line}"
+        end
+        if pattern.occurrences.length > @max_occurrences_shown
+          remaining = pattern.occurrences.length - @max_occurrences_shown
+          @output.puts "    … and #{remaining} more"
+        end
+      end
+    end
+
+    # Cap shape display length so deep nested patterns don't blow out
+    # the terminal. The fingerprint is what we match on; the shape is
+    # just for human inspection.
+    def truncate_shape(shape, limit: 120)
+      return shape if shape.length <= limit
+
+      "#{shape[0, limit - 3]}..."
+    end
+  end
+end

data/lib/guardrails/erb_parser.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "herb"
+
+module Guardrails
+  # Thin wrapper around the Herb ERB parser. Centralizes the call so:
+  #
+  #  - Detectors get a stable interface even if Herb's API drifts
+  #  - Parse failures degrade gracefully (return an empty document
+  #    rather than crashing the whole audit)
+  #  - Future caching / incremental-parse hooks have a single point
+  #    of attachment
+  #
+  # Detectors should walk `result.document`, an `Herb::AST::DocumentNode`.
+  # Position info on every node is `node.location`, which exposes a
+  # `start { line, column }` and `end { line, column }` (1-indexed lines,
+  # 0-indexed columns from Herb).
+  module ErbParser
+    Result = Struct.new(:document, :errors, :source, keyword_init: true) do
+      def success?
+        errors.nil? || errors.empty?
+      end
+    end
+
+    module_function
+
+    # Parse ERB source text. Returns a Result regardless of parse success
+    # — Herb crashes or value-less results both degrade to a safe
+    # empty-document Result so callers can always traverse `result.document`
+    # without nil-checking. Callers that care about strictness should check
+    # `result.success?` and inspect `result.errors`.
+    def parse(source)
+      herb_result = Herb.parse(source)
+      document = herb_result.value
+      if document.nil?
+        empty_result(source, ["herb returned no document for source"])
+      else
+        Result.new(
+          document: document,
+          errors: Array(herb_result.errors),
+          source: source
+        )
+      end
+    rescue StandardError => e
+      empty_result(source, ["#{e.class}: #{e.message}"])
+    end
+
+    # Build a Result around an empty parsed document so detectors that
+    # walk `result.document` see no elements rather than crashing.
+    def empty_result(source, errors)
+      empty = Herb.parse("")
+      Result.new(document: empty.value, errors: Array(errors), source: source)
+    rescue StandardError
+      # If Herb can't even parse "", give back a Result whose document
+      # responds to compact_child_nodes with []. Use a Struct-as-stub.
+      Result.new(document: NULL_DOCUMENT, errors: Array(errors), source: source)
+    end
+
+    NULL_DOCUMENT = Struct.new(:compact_child_nodes, :children, :location).new([], [], nil)
+    private_constant :NULL_DOCUMENT
+
+    # Walk an AST node depth-first, yielding each descendant (including
+    # the root). Callers filter by `node.class` or `node.tag_name`.
+    def each_node(node, &block)
+      return enum_for(:each_node, node) unless block_given?
+
+      yield node
+      compact_children(node).each { |child| each_node(child, &block) }
+    end
+
+    # Herb nodes expose either `compact_child_nodes` (preferred — skips
+    # nils and unwraps single-child wrappers) or just `children`.
+    def compact_children(node)
+      if node.respond_to?(:compact_child_nodes)
+        Array(node.compact_child_nodes)
+      elsif node.respond_to?(:children)
+        Array(node.children)
+      else
+        []
+      end
+    end
+
+    # Convert a Herb location to (line, column) for a node's start.
+    # Herb uses 1-indexed lines and 0-indexed columns; Guardrails violations
+    # use 1-indexed columns. This adjusts for that.
+    def start_position(node)
+      loc = node.location
+      [loc.start.line, loc.start.column + 1]
+    end
+  end
+end

data/lib/guardrails/hex_normalizer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Guardrails
+  module HexNormalizer
+    module_function
+
+    # Normalize a hex color literal for equality comparison:
+    # - lowercase
+    # - expand 3-char shorthand (#fa3 -> #ffaa33)
+    # - strip alpha channel (#ffaa3380 -> #ffaa33)
+    # - return non-hex input unchanged (after lowercasing)
+    def normalize(value)
+      v = value.to_s.downcase.strip
+      return v unless v.start_with?("#")
+
+      case v.length
+      when 4 # #fa3 -> #ffaa33
+        "#" + v[1..].chars.map { |c| c * 2 }.join
+      when 5 # #fa3a -> #ffaa33 (drop alpha)
+        ("#" + v[1..].chars.map { |c| c * 2 }.join)[0..6]
+      when 7 # #ffaa33 (canonical)
+        v
+      when 9 # #ffaa3380 -> #ffaa33
+        v[0..6]
+      else
+        v
+      end
+    end
+
+    # Maximum per-channel (R / G / B) difference between two normalized hex
+    # colors, on a 0..255 scale. Returns nil if either value isn't a
+    # 7-char hex after normalization. Distance 0 = identical color.
+    def distance(a, b)
+      a_norm = normalize(a)
+      b_norm = normalize(b)
+      return nil unless a_norm.length == 7 && a_norm.start_with?("#")
+      return nil unless b_norm.length == 7 && b_norm.start_with?("#")
+
+      diffs = [
+        (a_norm[1..2].to_i(16) - b_norm[1..2].to_i(16)).abs,
+        (a_norm[3..4].to_i(16) - b_norm[3..4].to_i(16)).abs,
+        (a_norm[5..6].to_i(16) - b_norm[5..6].to_i(16)).abs
+      ]
+      diffs.max
+    end
+  end
+end