ui_guardrails 1.0.0

data/lib/guardrails/lookbook/component_report.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "stringio"
+
+module Guardrails
+  module Lookbook
+    # Generates a per-component findings report meant to be rendered inside
+    # a Lookbook panel. Returns a Hash so the consumer can choose how to
+    # render it (HTML partial, JSON, etc).
+    class ComponentReport
+      def initialize(root:)
+        @root = Pathname(root)
+      end
+
+      # @param component_class_name [String] e.g. "ButtonComponent" or
+      #   "Admin::Users::ProfileComponent"
+      # @return [Hash, nil] nil when the component class can't be located
+      def for(component_class_name)
+        class_path = component_class_path(component_class_name)
+        return nil unless class_path&.exist?
+
+        template_path = class_path.sub_ext(".html.erb")
+        class_relative = relative(class_path)
+        template_relative = template_path.exist? ? relative(template_path) : nil
+
+        {
+          component: component_class_name,
+          class_file: class_relative,
+          template_file: template_relative,
+          violations: violations_for(template_relative),
+          orphan_slots: orphan_slots_for(class_relative),
+          similar_templates: similar_templates_for(template_relative)
+        }
+      end
+
+      private
+
+      def component_class_path(class_name)
+        relative = class_name.to_s
+                             .gsub("::", "/")
+                             .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                             .downcase
+        @root.join("app/components", "#{relative}.rb")
+      end
+
+      def relative(path)
+        path.relative_path_from(@root).to_s
+      end
+
+      def violations_for(template_relative)
+        return [] if template_relative.nil?
+
+        require_relative "../audit"
+        Guardrails::Audit.new(root: @root, output: StringIO.new).run
+          .select { |v| v.file == template_relative }
+          .map(&:to_h)
+      end
+
+      def orphan_slots_for(class_relative)
+        require_relative "../view_component_audit"
+        Guardrails::ViewComponentAudit.new(root: @root, output: StringIO.new).run.orphan_slots
+          .select { |o| o.file == class_relative }
+          .map(&:to_h)
+      end
+
+      def similar_templates_for(template_relative)
+        return [] if template_relative.nil?
+
+        require_relative "../partial_similarity"
+        Guardrails::PartialSimilarity.new(root: @root, output: StringIO.new).run
+          .select { |f| f.file_a == template_relative || f.file_b == template_relative }
+          .map { |f| { partner: (f.file_a == template_relative ? f.file_b : f.file_a), score: f.score } }
+      end
+    end
+  end
+end

data/lib/guardrails/lookbook/panel_registration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "component_report"
+
+module Guardrails
+  module Lookbook
+    # Registers a `:guardrails` Lookbook panel that renders ComponentReport
+    # findings inline next to each preview. The Railtie calls `register!`
+    # at app boot when `defined?(::Lookbook)`, so users no longer need to
+    # wire the panel by hand.
+    #
+    # Extracted from the Railtie so the registration logic and the
+    # locals lambda are unit-testable without booting Rails — pass a
+    # stub `lookbook` and the assertions can inspect what got registered.
+    module PanelRegistration
+      module_function
+
+      # The gem ships the panel partial inside `lib/guardrails/lookbook/views/`.
+      # Adding that dir to ActionView's view paths means the standard Rails
+      # partial-resolution machinery finds `lookbook_panels/_guardrails.html.erb`
+      # without users having to copy it into their app.
+      VIEW_PATH = File.expand_path("views", __dir__)
+
+      def register!(lookbook: ::Lookbook, view_consumer: nil)
+        append_view_path(view_consumer)
+        register_panel(lookbook)
+      end
+
+      # APPEND, not prepend — the host's `app/views` must keep precedence
+      # so that `app/views/lookbook_panels/_guardrails.html.erb` in the
+      # host wins over the gem's bundled default. Prepending would flip
+      # that and silently break the documented override mechanism.
+      def append_view_path(view_consumer = nil)
+        target = view_consumer || (defined?(::ActionController::Base) ? ::ActionController::Base : nil)
+        return unless target&.respond_to?(:append_view_path)
+
+        target.append_view_path(VIEW_PATH)
+      end
+
+      # Lookbook 2.x exposes `Lookbook.add_panel(name, partial_path, opts)`
+      # at the module level. opts[:locals] can be a callable that receives
+      # the inspector_data Store at render time and returns a Hash of
+      # locals for the partial. The pre-2.x API of
+      # `config.lookbook.preview_inspector.panels.add` doesn't exist.
+      def register_panel(lookbook = ::Lookbook)
+        return unless lookbook.respond_to?(:add_panel)
+
+        lookbook.add_panel(:guardrails, "lookbook_panels/guardrails", {
+          label: "Guardrails",
+          locals: ->(data) { { findings: report_for_preview(data) } }
+        })
+      end
+
+      def report_for_preview(data)
+        preview_class_name = preview_class_name_from(data)
+        return nil unless preview_class_name
+
+        component_class_name = component_class_name_from(preview_class_name)
+        return nil unless component_class_name
+
+        ComponentReport.new(root: ::Rails.root).for(component_class_name)
+      end
+
+      # Lookbook's inspector_data exposes the current preview's class via
+      # data.preview.preview_class_name (2.x) or data.preview.preview_class.name
+      # (older). Probe defensively rather than hardcoding one path.
+      def preview_class_name_from(data)
+        return nil if data.nil?
+
+        if data.respond_to?(:preview) && data.preview
+          preview = data.preview
+          return preview.preview_class_name if preview.respond_to?(:preview_class_name)
+          return preview.preview_class.name if preview.respond_to?(:preview_class)
+        end
+        return data.preview_class.name if data.respond_to?(:preview_class)
+
+        nil
+      end
+
+      # The preview class for a ViewComponent is conventionally
+      # `<Component>Preview` — Lookbook itself relies on this in
+      # `PreviewEntity#guess_render_targets`. Strip the suffix to get
+      # the component class name ComponentReport expects. If there's
+      # no `Preview` suffix we can't infer the target component, so
+      # we punt rather than guess.
+      def component_class_name_from(preview_class_name)
+        return nil unless preview_class_name.to_s.end_with?("Preview")
+
+        preview_class_name.to_s.chomp("Preview")
+      end
+    end
+  end
+end

data/lib/guardrails/lookbook/views/lookbook_panels/_guardrails.html.erb

@@ -0,0 +1,44 @@
+<% findings = local_assigns[:findings] %>
+<% if findings.nil? %>
+  <p class="lookbook-guardrails-empty">No Guardrails data for this component — Guardrails couldn't locate the component class file under <code>app/components/</code>.</p>
+<% else %>
+  <% violations      = findings[:violations] || [] %>
+  <% orphan_slots    = findings[:orphan_slots] || [] %>
+  <% similar         = findings[:similar_templates] || [] %>
+  <% any_findings    = violations.any? || orphan_slots.any? || similar.any? %>
+
+  <% if violations.any? %>
+    <h4>Drift in template</h4>
+    <ul>
+      <% violations.each do |v| %>
+        <li>
+          <strong><%= v[:type] %></strong>
+          <%= v[:file] %>:<%= v[:line] %>
+          — <code><%= v[:snippet] %></code>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+
+  <% if orphan_slots.any? %>
+    <h4>Orphan slots</h4>
+    <ul>
+      <% orphan_slots.each do |slot| %>
+        <li>:<%= slot[:slot] %> (<%= slot[:slot_kind] %>) declared but not rendered (<%= slot[:file] %>:<%= slot[:line] %>)</li>
+      <% end %>
+    </ul>
+  <% end %>
+
+  <% if similar.any? %>
+    <h4>Similar templates</h4>
+    <ul>
+      <% similar.each do |s| %>
+        <li><%= s[:partner] %> (<%= (s[:score] * 100).round %>% match)</li>
+      <% end %>
+    </ul>
+  <% end %>
+
+  <% unless any_findings %>
+    <p class="lookbook-guardrails-clean">No findings — this component is clean.</p>
+  <% end %>
+<% end %>

data/lib/guardrails/partial_similarity.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "set"
+require_relative "erb_parser"
+
+module Guardrails
+  class PartialSimilarity
+    Finding = Struct.new(:file_a, :file_b, :score, :tag_count_a, :tag_count_b, keyword_init: true)
+
+    DEFAULT_THRESHOLD = 0.7
+    DEFAULT_NGRAM_SIZE = 3
+    MIN_TAGS = 5
+
+    # Scan ERB partials (underscore-prefixed in app/views and app/components)
+    # AND ViewComponent sidecar templates (*_component.html.erb in app/components).
+    PARTIAL_PATTERNS = [
+      "app/views/**/_*.html.erb",
+      "app/components/**/_*.html.erb",
+      "app/components/**/*_component.html.erb"
+    ].freeze
+
+    def initialize(root:, output: $stdout, threshold: DEFAULT_THRESHOLD, ngram_size: DEFAULT_NGRAM_SIZE)
+      @root = Pathname(root)
+      @output = output
+      @threshold = threshold
+      @ngram_size = ngram_size
+    end
+
+    def run
+      findings = compute_findings
+      print_report(findings)
+      findings
+    end
+
+    def compute_findings
+      partials = collect_partials.filter_map do |path|
+        tokens = tokenize(File.read(path, encoding: Encoding::UTF_8))
+        next nil if tokens.length < MIN_TAGS
+
+        { path: path, tokens: tokens, ngrams: build_ngrams(tokens) }
+      end
+
+      findings = []
+      partials.combination(2).each do |a, b|
+        score = jaccard(a[:ngrams], b[:ngrams])
+        next if score < @threshold
+
+        findings << Finding.new(
+          file_a: a[:path].relative_path_from(@root).to_s,
+          file_b: b[:path].relative_path_from(@root).to_s,
+          score: score,
+          tag_count_a: a[:tokens].length,
+          tag_count_b: b[:tokens].length
+        )
+      end
+      findings.sort_by { |f| -f.score }
+    end
+
+    # Tokenize a partial into a flat sequence of HTML tag names by walking
+    # the parsed AST. Traversal is open-tag → recurse-into-body → close-tag
+    # so the resulting sequence preserves source order:
+    #
+    #   <div><span></span></div>  →  ["div", "span", "span", "div"]
+    #
+    # ERB nodes don't contribute tokens. Void elements (img, input)
+    # produce one token; their close-tag pass is skipped.
+    def tokenize(content)
+      tokens = []
+      result = ErbParser.parse(content)
+      walk_for_tokens(result.document, tokens)
+      tokens
+    end
+
+    def walk_for_tokens(node, tokens)
+      case node
+      when ::Herb::AST::HTMLElementNode
+        name = element_tag_name(node)
+        if name
+          tokens << name
+          Array(node.body).each { |child| walk_for_tokens(child, tokens) }
+          tokens << name unless void_element_name?(name)
+        end
+      when ::Herb::AST::HTMLOpenTagNode
+        # Top-level void element not wrapped in HTMLElementNode.
+        name = open_tag_name(node)
+        tokens << name if name && void_element_name?(name)
+      else
+        ErbParser.compact_children(node).each { |child| walk_for_tokens(child, tokens) }
+      end
+    end
+
+    VOID_ELEMENT_NAMES = %w[
+      area base br col embed hr img input link meta param source track wbr
+    ].to_set.freeze
+
+    def void_element_name?(name)
+      VOID_ELEMENT_NAMES.include?(name)
+    end
+
+    def open_tag_name(node)
+      tok = node.respond_to?(:tag_name) ? node.tag_name : nil
+      tok && tok.respond_to?(:value) ? tok.value.to_s.downcase : nil
+    end
+
+    def element_tag_name(element)
+      open_tag_name(element.open_tag) if element.respond_to?(:open_tag) && element.open_tag
+    end
+
+    # Group findings by connected component over the similarity graph.
+    # When N partials are pairwise above-threshold (e.g. 8 templated
+    # public_activity partials all matching each other at 1.00), the
+    # naive pair list emits C(N,2) lines that read as noise; collapsing
+    # to one group of N is what the user actually cares about.
+    #
+    # Returns an Array of Hashes keyed by:
+    #   :files       — sorted Array of file paths in the component
+    #   :score_min, :score_max — observed score range across the
+    #                            component's pairs
+    #   :pair_count  — how many original pairs fed into the group
+    #   :sample_pair — a representative Finding (the only one for size-2
+    #                  components, used to preserve the original pair
+    #                  line's tag-count detail)
+    def group_findings(findings)
+      adj = Hash.new { |h, k| h[k] = Set.new }
+      pairs_by_file = Hash.new { |h, k| h[k] = [] }
+      findings.each do |f|
+        adj[f.file_a] << f.file_b
+        adj[f.file_b] << f.file_a
+        pairs_by_file[f.file_a] << f
+        pairs_by_file[f.file_b] << f
+      end
+
+      visited = Set.new
+      groups = []
+      adj.each_key do |file|
+        next if visited.include?(file)
+
+        component = Set.new
+        stack = [file]
+        until stack.empty?
+          current = stack.pop
+          next if component.include?(current)
+
+          component << current
+          visited << current
+          adj[current].each { |neighbor| stack << neighbor unless component.include?(neighbor) }
+        end
+
+        # Walk only the findings touching files in this component (via the
+        # pre-built index) — avoids the O(components × pairs) scan.
+        seen_pair_ids = Set.new
+        component_pairs = []
+        component.each do |f|
+          pairs_by_file[f].each do |pair|
+            next unless component.include?(pair.file_a) && component.include?(pair.file_b)
+            next if seen_pair_ids.include?(pair.object_id)
+
+            seen_pair_ids << pair.object_id
+            component_pairs << pair
+          end
+        end
+
+        scores = component_pairs.map(&:score)
+        groups << {
+          files: component.to_a.sort,
+          score_min: scores.min,
+          score_max: scores.max,
+          pair_count: component_pairs.size,
+          sample_pair: component_pairs.first
+        }
+      end
+      groups.sort_by { |g| -g[:files].size }
+    end
+
+    private
+
+    def collect_partials
+      PARTIAL_PATTERNS
+        .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+        .map { |path| Pathname(path) }
+        .uniq
+        .sort
+    end
+
+    def build_ngrams(tokens)
+      return Set.new([tokens]) if tokens.length < @ngram_size
+
+      tokens.each_cons(@ngram_size).to_set
+    end
+
+    def jaccard(set_a, set_b)
+      return 0.0 if set_a.empty? && set_b.empty?
+
+      intersection = (set_a & set_b).size.to_f
+      union = (set_a | set_b).size
+      intersection / union
+    end
+
+    def print_report(findings)
+      return if findings.empty?
+
+      groups = group_findings(findings)
+      total_files = groups.sum { |g| g[:files].size }
+
+      @output.puts ""
+      group_noun = groups.length == 1 ? "group" : "groups"
+      @output.puts "Guardrails templates: #{groups.length} similar #{group_noun} (#{findings.length} pairs across #{total_files} files; >= #{@threshold} structural similarity)"
+
+      groups.each do |group|
+        if group[:files].length == 2
+          # Use the original Finding so we keep the tag-count suffix
+          # (e.g. "(12 / 14 tags)") that single-pair output has always
+          # included. The sorted file list is still authoritative for
+          # display order.
+          pair = group[:sample_pair]
+          file_a, file_b = group[:files]
+          @output.puts "  #{format('%.2f', group[:score_max])}  #{file_a} ↔ #{file_b}  (#{pair.tag_count_a} / #{pair.tag_count_b} tags)"
+        else
+          score_label = if group[:score_min] == group[:score_max]
+                         format("%.2f", group[:score_max])
+                       else
+                         "#{format('%.2f', group[:score_min])}–#{format('%.2f', group[:score_max])}"
+                       end
+          @output.puts "  Group of #{group[:files].length} templates (#{score_label}, #{group[:pair_count]} pairs):"
+          group[:files].each { |f| @output.puts "    #{f}" }
+        end
+      end
+    end
+  end
+end

data/lib/guardrails/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Guardrails
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/guardrails.rake", __dir__)
+    end
+
+    # Auto-register the Lookbook panel when Lookbook is on the load path.
+    # Pre-0.5.0 users had to wire the panel by hand in an initializer
+    # (see doc/LOOKBOOK.md history); now the gem ships the partial and
+    # registers it on boot. Run after Lookbook's own initializers so
+    # `Lookbook.add_panel` is available.
+    initializer "guardrails.lookbook_panel", after: :load_config_initializers do
+      next unless defined?(::Lookbook)
+
+      require_relative "lookbook/panel_registration"
+      ::Guardrails::Lookbook::PanelRegistration.register!
+    end
+  end
+end

data/lib/guardrails/stimulus_audit.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Guardrails
+  class StimulusAudit
+    Result = Struct.new(:orphaned, :dead, keyword_init: true) do
+      def violations?
+        !orphaned.empty? || !dead.empty?
+      end
+    end
+
+    # Stimulus controller files can live under different layouts depending
+    # on bundler / app structure:
+    #
+    #   app/javascript/controllers/*_controller.{js,ts}        (importmap default)
+    #   app/javascript/js/controllers/*_controller.{js,ts}     (Avo)
+    #   app/javascript/packs/controllers/*_controller.{js,ts}  (older Webpacker)
+    #   app/frontend/controllers/*_controller.{js,ts}          (Vite Rails)
+    #
+    # Glob from each accepted base; controller-name derivation hinges on
+    # the deepest `controllers/` segment in the path.
+    CONTROLLER_BASES = %w[app/javascript app/frontend].freeze
+    CONTROLLER_GLOB = "**/*_controller.{js,ts}"
+
+    VIEW_PATTERNS = [
+      "app/views/**/*.html.erb",
+      "app/components/**/*.html.erb"
+    ].freeze
+
+    DATA_CONTROLLER_PATTERN = /data-controller\s*=\s*["']([^"']+)["']/
+
+    # Ruby helper syntax: `tag.div(data: { controller: "foo" })` or
+    # `link_to "x", url, data: { controller: "foo bar" }`. Allow `=>` rocket
+    # syntax too. Capture the string passed as the `controller:` value.
+    RUBY_DATA_CONTROLLER_PATTERN =
+      /data:?\s*(?:=>)?\s*\{[^}]*?controller:?\s*(?:=>)?\s*["']([^"']+)["']/m
+
+    def initialize(root:, output: $stdout)
+      @root = Pathname(root)
+      @output = output
+    end
+
+    def run
+      defined = collect_defined_controllers
+      referenced = collect_referenced_controllers
+
+      result = Result.new(
+        orphaned: (referenced - defined).sort,
+        dead: (defined - referenced).sort
+      )
+
+      print_report(result)
+      result
+    end
+
+    private
+
+    def collect_defined_controllers
+      paths = CONTROLLER_BASES.flat_map do |base|
+        absolute = @root.join(base)
+        next [] unless absolute.exist?
+
+        Dir.glob(absolute.join(CONTROLLER_GLOB))
+      end
+      paths.map { |path| controller_name_from_path(path) }.compact.uniq
+    end
+
+    # Derive a Stimulus controller identifier from a file path. We anchor
+    # on the deepest `controllers/` directory in the path, so:
+    #
+    #   app/javascript/controllers/users/profile_controller.js → "users--profile"
+    #   app/javascript/js/controllers/foo_controller.js        → "foo"
+    #   app/frontend/controllers/admin/users_controller.ts     → "admin--users"
+    #
+    # Falls back to the basename when no `controllers/` segment exists.
+    def controller_name_from_path(path)
+      str = path.to_s
+      marker = "/controllers/"
+      idx = str.rindex(marker)
+      relative = idx ? str[(idx + marker.length)..] : File.basename(str)
+
+      stripped = relative.sub(/_controller\.(js|ts)\z/, "")
+      return nil if stripped.empty?
+
+      stripped.gsub("/", "--").tr("_", "-")
+    end
+
+    def collect_referenced_controllers
+      VIEW_PATTERNS.flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+        .flat_map { |path| extract_referenced(Pathname(path)) }
+        .uniq
+    end
+
+    def extract_referenced(file)
+      content = File.read(file, encoding: Encoding::UTF_8)
+      [DATA_CONTROLLER_PATTERN, RUBY_DATA_CONTROLLER_PATTERN].flat_map do |pattern|
+        content.scan(pattern).flat_map { |captures| captures[0].strip.split(/\s+/) }
+      end
+    end
+
+    def print_report(result)
+      return unless result.violations?
+
+      @output.puts ""
+      unless result.orphaned.empty?
+        noun = result.orphaned.length == 1 ? "controller" : "controllers"
+        @output.puts "Guardrails stimulus: #{result.orphaned.length} orphaned #{noun} (referenced in HTML, no JS file)"
+        result.orphaned.each { |name| @output.puts "  - #{name}" }
+      end
+      unless result.dead.empty?
+        noun = result.dead.length == 1 ? "controller" : "controllers"
+        @output.puts "Guardrails stimulus: #{result.dead.length} dead #{noun} (JS file, never referenced)"
+        result.dead.each { |name| @output.puts "  - #{name}" }
+      end
+    end
+  end
+end

data/lib/guardrails/token_matcher.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "hex_normalizer"
+
+module Guardrails
+  class TokenMatcher
+    NEAR_MATCH_THRESHOLD = 4
+
+    Match = Struct.new(:token, :kind, :distance, keyword_init: true)
+
+    def initialize(tokens, near_match_threshold: NEAR_MATCH_THRESHOLD)
+      @tokens = tokens
+      @lookup = tokens.to_h { |t| [HexNormalizer.normalize(t.value), t] }
+      @near_match_threshold = near_match_threshold
+    end
+
+    def match(value)
+      return nil if value.nil?
+
+      exact = @lookup[HexNormalizer.normalize(value)]
+      return Match.new(token: exact, kind: :exact, distance: 0) if exact
+
+      best = nil
+      best_distance = @near_match_threshold + 1
+      @tokens.each do |t|
+        d = HexNormalizer.distance(value, t.value)
+        next unless d
+        next if d.zero?
+
+        if d < best_distance
+          best = t
+          best_distance = d
+        end
+      end
+      return nil unless best
+
+      Match.new(token: best, kind: :near, distance: best_distance)
+    end
+  end
+end