ui_guardrails 1.0.0

data/lib/guardrails/tokens/tailwind_config_parser.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Guardrails
+  class Tokens
+    # Best-effort regex/character-walk parser for Tailwind v3 config files.
+    # Extracts color entries from `theme.colors` and `theme.extend.colors`
+    # blocks. Handles flat scalars and one level of nested scales (per
+    # Tailwind convention: `gray: { 50: "#f9fafb" }` flattens to
+    # `gray-50`).
+    #
+    # Known limitations (out of scope for V0):
+    # - Function-valued entries (`primary: defineColor("blue")`)
+    # - Spread operators (`...palette`)
+    # - require()/import() of external palettes
+    # - Computed keys
+    # - TypeScript configs with type annotations on values
+    #
+    # For any of these the entry is silently skipped; the user is
+    # encouraged to migrate to Tailwind v4 `@theme` (CSS-first) which
+    # parses cleanly through the existing CSS custom property path.
+    class TailwindConfigParser
+      Entry = Struct.new(:name, :value, keyword_init: true)
+
+      COLORS_BLOCK_HEADER = /\bcolors\s*:\s*\{/
+
+      def self.parse(content)
+        new(content).parse
+      end
+
+      def initialize(content)
+        @content = content
+      end
+
+      def parse
+        entries = []
+        scan_colors_blocks do |body|
+          entries.concat(extract_entries(body))
+        end
+        entries
+      end
+
+      private
+
+      def scan_colors_blocks
+        pos = 0
+        while (m = @content.match(COLORS_BLOCK_HEADER, pos))
+          brace_idx = m.end(0) - 1
+          body = balanced_extract(@content, brace_idx)
+          break unless body
+
+          yield body
+          pos = brace_idx + body.length + 2
+        end
+      end
+
+      def balanced_extract(text, start_idx)
+        return nil unless text[start_idx] == "{"
+
+        depth = 0
+        i = start_idx
+        while i < text.length
+          case text[i]
+          when "{" then depth += 1
+          when "}" then depth -= 1
+          end
+          return text[(start_idx + 1)...i] if depth.zero?
+
+          i += 1
+        end
+        nil
+      end
+
+      def extract_entries(body)
+        entries = []
+        i = 0
+        while i < body.length
+          i = skip_separators(body, i)
+          break if i >= body.length
+
+          key, advance = parse_key(body, i)
+          unless key
+            # Unparseable token at this position (e.g. `...spread` or a
+            # syntax we don't support). Skip to the next comma and keep going
+            # rather than abandoning subsequent entries.
+            i = body.index(/,/, i) || body.length
+            i += 1 if i < body.length
+            next
+          end
+
+          i = skip_to_value(body, i + advance)
+          break if i >= body.length
+
+          if body[i] == "{"
+            nested = balanced_extract(body, i)
+            break unless nested
+
+            extract_entries(nested).each do |child|
+              entries << Entry.new(name: "#{key}-#{child.name}", value: child.value)
+            end
+            i += nested.length + 2
+          elsif (quote = body[i]) =~ /["']/
+            end_idx = body.index(quote, i + 1)
+            break unless end_idx
+
+            entries << Entry.new(name: key, value: body[(i + 1)...end_idx])
+            i = end_idx + 1
+          else
+            i = body.index(/,/, i) || body.length
+          end
+        end
+        entries
+      end
+
+      def skip_separators(body, i)
+        i += 1 while i < body.length && body[i] =~ /[\s,]/
+        i
+      end
+
+      def skip_to_value(body, i)
+        i += 1 while i < body.length && body[i] =~ /[\s:]/
+        i
+      end
+
+      def parse_key(body, start)
+        if body[start] =~ /["']/
+          quote = body[start]
+          end_idx = body.index(quote, start + 1)
+          return [nil, 0] unless end_idx
+
+          [body[(start + 1)...end_idx], end_idx - start + 1]
+        else
+          m = body[start..].match(/\A([a-zA-Z_0-9][\w-]*)/)
+          return [nil, 0] unless m
+
+          [m[1], m[1].length]
+        end
+      end
+    end
+  end
+end

data/lib/guardrails/tokens.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+require_relative "hex_normalizer"
+require_relative "tokens/tailwind_config_parser"
+
+module Guardrails
+  class Tokens
+    Token = Struct.new(:name, :value, :syntax, :file, :line, keyword_init: true)
+    Drift = Struct.new(:file, :line, :column, :value, :matched_token, keyword_init: true)
+
+    CSS_VAR_PATTERN = /--([a-z][\w-]*):\s*([^;]+);/i
+    SCSS_VAR_PATTERN = /\$([a-z][\w-]*):\s*([^;]+);/i
+    HEX_LITERAL_PATTERN = /#[0-9a-fA-F]{3,8}\b/
+    BLOCK_COMMENT_PATTERN = /\/\*[\s\S]*?\*\//
+    LINE_COMMENT_PATTERN = /\/\/[^\n]*/
+    STYLESHEET_PATTERNS = [
+      "app/assets/stylesheets/**/*.{css,scss}",
+      "app/assets/tailwind/**/*.css"
+    ].freeze
+
+    # Same path-component skip-list as Audit / StackDetector — vendor
+    # stylesheets nested under app/assets/stylesheets/ shouldn't surface
+    # as drift since they're typically third-party.
+    IMPLICIT_IGNORE_SEGMENTS = %w[vendor node_modules tmp public log].freeze
+
+    def initialize(root:, output: $stdout)
+      @root = Pathname(root)
+      @output = output
+      @config = load_config
+    end
+
+    def run
+      tokens = parse_tokens
+      drift = detect_drift(tokens)
+      print_summary(tokens)
+      print_drift(drift)
+      { tokens: tokens, drift: drift }
+    end
+
+    def parse_tokens
+      tokens = []
+      [colors_file, type_scale_file].compact.each do |file|
+        next unless file.exist?
+
+        content = File.read(file, encoding: Encoding::UTF_8)
+        tokens.concat(scan(content, file, CSS_VAR_PATTERN, :css_var))
+        tokens.concat(scan(content, file, SCSS_VAR_PATTERN, :scss_var))
+      end
+      tokens.concat(parse_tailwind_config)
+      tokens
+    end
+
+    def parse_tailwind_config
+      # Reset on every call — a Tokens instance can outlive a single run
+      # (callers may reuse it), and tailwind.config.js can change between
+      # runs. Without this, the hint can leak into later summaries after
+      # the config no longer matches the preset pattern.
+      @tailwind_preset_hint = nil
+
+      file = @root.join("tailwind.config.js")
+      return [] unless file.exist?
+
+      content = File.read(file, encoding: Encoding::UTF_8)
+      entries = TailwindConfigParser.parse(content)
+
+      # If the literal config has zero parseable entries but uses the
+      # preset import pattern, the actual tokens live in a JS file we
+      # can't evaluate. Surface a one-line hint so users don't think
+      # the parser is broken — found in the Avo dogfood where
+      # tailwind.config.js does `module.exports = { presets: [preset] }`.
+      if entries.empty? && tailwind_uses_presets?(content)
+        @tailwind_preset_hint =
+          "tailwind.config.js uses a `presets:` import; only the literal config file " \
+            "is parsed (we don't evaluate JS). Define non-color tokens in v4 `@theme` " \
+            "blocks for cross-tool token visibility."
+      end
+
+      entries.map do |entry|
+        Token.new(
+          name: entry.name,
+          value: entry.value,
+          syntax: :tailwind,
+          file: file.relative_path_from(@root).to_s,
+          line: 0
+        )
+      end
+    end
+
+    def detect_drift(tokens)
+      lookup = tokens.to_h { |t| [HexNormalizer.normalize(t.value), t] }
+      drift = []
+      definition_files = [colors_file, type_scale_file].compact
+
+      stylesheets.each do |file|
+        next if definition_files.include?(file)
+        next if file == @root.join("tailwind.config.js")
+
+        raw_content = File.read(file, encoding: Encoding::UTF_8)
+        content = strip_comments(raw_content)
+        content.each_line.with_index do |line, idx|
+          next if variable_definition_line?(line)
+
+          line.scan(HEX_LITERAL_PATTERN) do
+            value = Regexp.last_match[0]
+            column = Regexp.last_match.begin(0) + 1
+            drift << Drift.new(
+              file: file.relative_path_from(@root).to_s,
+              line: idx + 1,
+              column: column,
+              value: value,
+              matched_token: lookup[HexNormalizer.normalize(value)]
+            )
+          end
+        end
+      end
+      drift
+    end
+
+    private
+
+    def tailwind_uses_presets?(content)
+      content.match?(/\bpresets\s*:/)
+    end
+
+    def load_config
+      path = @root.join("guardrails.yml")
+      return {} unless path.exist?
+
+      YAML.safe_load_file(path) || {}
+    end
+
+    def colors_file
+      configured_token_file("colors_file")
+    end
+
+    def type_scale_file
+      configured_token_file("type_scale_file")
+    end
+
+    def configured_token_file(key)
+      relative = @config.dig("guardrails", "tokens", key)
+      return nil unless relative
+
+      @root.join(relative)
+    end
+
+    def scan(content, file, pattern, syntax)
+      tokens = []
+      content.each_line.with_index do |line, idx|
+        line.scan(pattern) do
+          match = Regexp.last_match
+          tokens << Token.new(
+            name: match[1],
+            value: match[2].strip,
+            syntax: syntax,
+            file: file.relative_path_from(@root).to_s,
+            line: idx + 1
+          )
+        end
+      end
+      tokens
+    end
+
+    def stylesheets
+      STYLESHEET_PATTERNS
+        .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+        .map { |path| Pathname(path) }
+        .uniq
+        .reject { |path| ignored_segment?(path) }
+    end
+
+    def ignored_segment?(path)
+      segments = path.relative_path_from(@root).to_s.split("/")
+      (IMPLICIT_IGNORE_SEGMENTS & segments).any?
+    end
+
+    def variable_definition_line?(line)
+      line.match?(SCSS_VAR_PATTERN) || line.match?(CSS_VAR_PATTERN)
+    end
+
+    # Replace CSS/SCSS comments with whitespace, preserving line/column
+    # positions so reported drift coordinates remain accurate.
+    def strip_comments(content)
+      content
+        .gsub(BLOCK_COMMENT_PATTERN) { |m| mask_chars(m) }
+        .gsub(LINE_COMMENT_PATTERN) { |m| " " * m.length }
+    end
+
+    def mask_chars(string)
+      string.gsub(/[^\n]/, " ")
+    end
+
+    def print_drift(drift)
+      return if drift.empty?
+
+      @output.puts ""
+      @output.puts "Guardrails tokens: #{drift.length} color literal#{'s' if drift.length != 1} found in stylesheets outside the token file"
+      drift.each do |d|
+        suffix = d.matched_token ? " — matches #{format_token_name(d.matched_token)}" : " — no matching token"
+        @output.puts "  #{d.file}:#{d.line}:#{d.column}  #{d.value}#{suffix}"
+      end
+    end
+
+    def format_token_name(token)
+      case token.syntax
+      when :css_var then "var(--#{token.name})"
+      when :scss_var then "$#{token.name}"
+      when :tailwind then "Tailwind theme color `#{token.name}`"
+      else token.name.to_s
+      end
+    end
+
+    def print_summary(tokens)
+      # Iterate the two config entries explicitly so the missing-file
+      # message names the right YAML key even when both keys point at
+      # the same path (Pathname equality alone can't tell them apart).
+      configured_entries = [
+        ["tokens.colors_file", colors_file],
+        ["tokens.type_scale_file", type_scale_file]
+      ].select { |_key, path| path }
+
+      tailwind_path = @root.join("tailwind.config.js")
+      tailwind_source = tailwind_path.exist? ? tailwind_path : nil
+      all_sources = configured_entries.map { |_, p| p } + [tailwind_source].compact
+
+      if all_sources.empty?
+        @output.puts "Guardrails tokens: no colors_file, type_scale_file, or tailwind.config.js found"
+        return
+      end
+
+      missing = configured_entries.reject { |_, path| path.exist? }
+      if missing.any?
+        missing.each do |key, path|
+          relative = path.relative_path_from(@root)
+          @output.puts "Guardrails tokens: configured #{key} does not exist (#{relative})"
+        end
+        @output.puts "  → Edit guardrails.yml to point at your real token file, or set FORCE=1 and re-run guardrails:init to regenerate config."
+      end
+
+      existing_sources = all_sources.select(&:exist?)
+      return if existing_sources.empty?
+
+      labels = existing_sources.map { |f| f.relative_path_from(@root).to_s }.join(", ")
+      if tokens.empty?
+        @output.puts "Guardrails tokens: 0 tokens found in #{labels}"
+        @output.puts "  → #{@tailwind_preset_hint}" if @tailwind_preset_hint
+        return
+      end
+      @output.puts "Guardrails tokens: #{tokens.length} token#{'s' if tokens.length != 1} found in #{labels}"
+      @output.puts "  → #{@tailwind_preset_hint}" if @tailwind_preset_hint
+      tokens.each { |t| @output.puts "  #{format_token_name(t)} = #{t.value}" }
+    end
+  end
+end

data/lib/guardrails/version.rb

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

data/lib/guardrails/view_component_audit.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Guardrails
+  class ViewComponentAudit
+    Result = Struct.new(:missing_previews, :orphan_slots, keyword_init: true) do
+      def violations?
+        !missing_previews.empty? || !orphan_slots.empty?
+      end
+    end
+
+    OrphanSlot = Struct.new(:component, :slot, :slot_kind, :file, :line, keyword_init: true)
+
+    COMPONENT_DIR = "app/components"
+    COMPONENT_GLOB = "**/*_component.rb"
+    PREVIEW_DIRS = [
+      "test/components/previews",
+      "spec/components/previews"
+    ].freeze
+    PREVIEW_GLOB = "**/*_component_preview.rb"
+
+    SLOT_PATTERN = /^\s*(renders_one|renders_many)\s+:([a-z_][\w]*)/
+
+    def initialize(root:, output: $stdout)
+      @root = Pathname(root)
+      @output = output
+    end
+
+    def run
+      result = Result.new(
+        missing_previews: find_missing_previews,
+        orphan_slots: find_orphan_slots
+      )
+      print_report(result)
+      result
+    end
+
+    def find_missing_previews
+      defined = collect_components
+      previewed = collect_previews
+      (defined - previewed).sort
+    end
+
+    def find_orphan_slots
+      orphans = []
+      component_files.each do |path|
+        slots = parse_slot_declarations(path)
+        next if slots.empty?
+
+        template_path = template_for(path)
+        template_content = template_path.exist? ? File.read(template_path, encoding: Encoding::UTF_8) : ""
+
+        slots.each do |slot|
+          next if rendered_in_template?(template_content, slot[:name])
+
+          orphans << OrphanSlot.new(
+            component: relative_component_name(path),
+            slot: slot[:name],
+            slot_kind: slot[:kind],
+            file: path.relative_path_from(@root).to_s,
+            line: slot[:line]
+          )
+        end
+      end
+      orphans
+    end
+
+    private
+
+    def component_files
+      base = @root.join(COMPONENT_DIR)
+      return [] unless base.exist?
+
+      Dir.glob(base.join(COMPONENT_GLOB)).map { |p| Pathname(p) }.sort
+    end
+
+    def collect_components
+      base = @root.join(COMPONENT_DIR)
+      return [] unless base.exist?
+
+      Dir.glob(base.join(COMPONENT_GLOB)).map do |p|
+        component_name(Pathname(p).relative_path_from(base))
+      end
+    end
+
+    def collect_previews
+      PREVIEW_DIRS.flat_map do |dir|
+        base = @root.join(dir)
+        next [] unless base.exist?
+
+        Dir.glob(base.join(PREVIEW_GLOB)).map do |p|
+          preview_name(Pathname(p).relative_path_from(base))
+        end
+      end.uniq
+    end
+
+    def component_name(relative_path)
+      relative_path.to_s.sub(/_component\.rb\z/, "")
+    end
+
+    def preview_name(relative_path)
+      relative_path.to_s.sub(/_component_preview\.rb\z/, "")
+    end
+
+    def relative_component_name(path)
+      base = @root.join(COMPONENT_DIR)
+      component_name(path.relative_path_from(base))
+    end
+
+    def template_for(component_path)
+      component_path.sub_ext(".html.erb")
+    end
+
+    def parse_slot_declarations(path)
+      slots = []
+      File.read(path, encoding: Encoding::UTF_8).each_line.with_index do |line, idx|
+        m = line.match(SLOT_PATTERN)
+        next unless m
+
+        slots << { kind: m[1].to_sym, name: m[2], line: idx + 1 }
+      end
+      slots
+    end
+
+    def rendered_in_template?(content, slot_name)
+      # Look for any reference to the slot — `<%= slot_name %>`, `slot_name?`,
+      # or `slot_name.each` / `slot_name.map` for renders_many.
+      content.match?(/\b#{Regexp.escape(slot_name)}\b/)
+    end
+
+    def print_report(result)
+      return unless result.violations?
+
+      @output.puts ""
+      unless result.missing_previews.empty?
+        noun = result.missing_previews.length == 1 ? "component" : "components"
+        @output.puts "Guardrails view_components: #{result.missing_previews.length} #{noun} without a preview"
+        result.missing_previews.each { |name| @output.puts "  - #{name}_component.rb (no #{name}_component_preview.rb)" }
+      end
+      unless result.orphan_slots.empty?
+        noun = result.orphan_slots.length == 1 ? "slot declared" : "slots declared"
+        @output.puts "Guardrails view_components: #{result.orphan_slots.length} #{noun} but never referenced in template"
+        result.orphan_slots.each do |o|
+          @output.puts "  - #{o.component}_component: :#{o.slot} (#{o.slot_kind} at #{o.file}:#{o.line})"
+        end
+      end
+    end
+  end
+end

data/lib/guardrails/visual_diff/snap_diff.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Guardrails
+  class VisualDiff
+    # Adapter for snap_diff-capybara (formerly capybara-screenshot-diff).
+    # The gem commits baselines to git under `doc/screenshots/` by
+    # convention. After a failed run there's a `<name>.diff.png` sibling
+    # next to `<name>.png`. Walking the directory tree and pairing names
+    # gives us a binary pass/fail per scenario without needing snap_diff
+    # to emit a JSON report (see upstream issue — TODO: link once filed).
+    #
+    # Limits:
+    # - No mismatch percentage; snap_diff is binary at the filesystem
+    #   level. Findings emit `mismatch_ratio: nil` and VisualDiff treats
+    #   nil as "unconditionally failing" (any diff fails).
+    # - No URL / viewport / selector — those live in snap_diff's
+    #   Capybara tests, not the artifact tree. Adapters that have them
+    #   (BackstopJS, issue #15) populate the optional fields.
+    class SnapDiff
+      DIFF_SUFFIX = ".diff.png"
+      HEATMAP_SUFFIX = ".heatmap.diff.png"
+
+      def initialize(root:, dir:)
+        @root = Pathname(root)
+        @dir = @root.join(dir)
+      end
+
+      def collect
+        return [] unless @dir.directory?
+
+        diff_files.map { |diff| build_finding(diff) }.compact
+      end
+
+      private
+
+      # Find every `<name>.diff.png` under @dir, recursively. Skip
+      # `<name>.heatmap.diff.png` files — those are visualization
+      # companions, not separate findings.
+      def diff_files
+        Pathname.glob(@dir.join("**/*#{DIFF_SUFFIX}")).reject do |path|
+          path.basename.to_s.end_with?(HEATMAP_SUFFIX)
+        end
+      end
+
+      def build_finding(diff_path)
+        baseline_path = baseline_for(diff_path)
+        ::Guardrails::VisualDiff::Finding.new(
+          scenario: scenario_name(diff_path),
+          viewport: nil,
+          mismatch_ratio: nil, # snap_diff is binary at the FS layer
+          baseline_path: relative(baseline_path),
+          current_path: nil,   # snap_diff doesn't keep a separate "current" image after the test run
+          diff_path: relative(diff_path),
+          url: nil,
+          selector: nil
+        )
+      end
+
+      # `name.diff.png` → `name.png` (sibling baseline).
+      def baseline_for(diff_path)
+        stem = diff_path.basename.to_s.sub(/#{Regexp.escape(DIFF_SUFFIX)}\z/, ".png")
+        diff_path.dirname.join(stem)
+      end
+
+      # Scenario label = path under @dir without the `.diff.png` suffix,
+      # so `doc/screenshots/checkout/cart.diff.png` → "checkout/cart".
+      def scenario_name(diff_path)
+        rel = diff_path.relative_path_from(@dir).to_s
+        rel.sub(/#{Regexp.escape(DIFF_SUFFIX)}\z/, "")
+      end
+
+      def relative(path)
+        return nil if path.nil?
+
+        path.relative_path_from(@root).to_s
+      end
+    end
+  end
+end