ui_guardrails 1.0.0

data/lib/guardrails/a11y_audit.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "set"
+require_relative "erb_parser"
+
+module Guardrails
+  # Static a11y checks that don't require a browser — element-level rules
+  # that can be answered from the source. For runtime a11y (color contrast,
+  # focus order, ARIA tree, dynamic content) integrate axe-core-rspec
+  # alongside Guardrails; see doc/A11Y.md.
+  class A11yAudit
+    Finding = Struct.new(:rule, :file, :line, :column, :snippet, keyword_init: true) do
+      def to_h
+        { rule: rule, file: file, line: line, column: column, snippet: snippet }
+      end
+    end
+
+    SCAN_PATTERNS = [
+      "app/views/**/*.html.erb",
+      "app/components/**/*.html.erb"
+    ].freeze
+
+    NON_INTERACTIVE_INPUT_TYPES = %w[hidden submit button reset image].freeze
+
+    def initialize(root:, output: $stdout)
+      @root = Pathname(root)
+      @output = output
+    end
+
+    def run
+      findings = view_files.flat_map { |path| scan_file(path) }
+      print_report(findings)
+      findings
+    end
+
+    private
+
+    def view_files
+      SCAN_PATTERNS
+        .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+        .map { |path| Pathname(path) }
+        .uniq
+    end
+
+    def scan_file(path)
+      content = File.read(path, encoding: Encoding::UTF_8)
+      lines = content.lines
+      result = ErbParser.parse(content)
+      @current_document = result.document
+      @label_for_cache = nil
+
+      findings = []
+      ErbParser.each_node(result.document) do |node|
+        case node
+        when ::Herb::AST::HTMLElementNode then findings.concat(check_element(node, path, lines))
+        when ::Herb::AST::HTMLOpenTagNode then findings.concat(check_void(node, path, lines)) if void_tag?(node)
+        end
+      end
+      findings
+    ensure
+      @current_document = nil
+      @label_for_cache = nil
+    end
+
+    def check_element(element, file, lines)
+      tag = element_tag_name(element)
+      case tag
+      when "button" then check_button(element, file, lines)
+      when "a" then check_link(element, file, lines)
+      else []
+      end
+    end
+
+    def check_void(open_tag, file, lines)
+      tag = open_tag_name(open_tag)
+      case tag
+      when "img" then check_img(open_tag, file, lines)
+      when "input" then check_input(open_tag, file, lines)
+      else []
+      end
+    end
+
+    def check_img(open_tag, file, lines)
+      return [] if attribute_present?(open_tag, "alt")
+
+      [build_finding(:image_alt, open_tag, file, lines)]
+    end
+
+    def check_button(element, file, lines)
+      attrs_node = element.open_tag
+      return [] if attribute_present?(attrs_node, "aria-label") || attribute_present?(attrs_node, "aria-labelledby")
+      # Defer to helper_recommended for ERB-output bodies — the suggestion
+      # there is more actionable than a generic missing-name flag.
+      return [] if body_contains_erb_output?(element)
+      return [] if visible_text_in(element).length.positive?
+
+      [build_finding(:button_name, attrs_node, file, lines)]
+    end
+
+    def check_link(element, file, lines)
+      attrs_node = element.open_tag
+      return [] unless attribute_present?(attrs_node, "href")
+      return [] if attribute_present?(attrs_node, "aria-label") || attribute_present?(attrs_node, "aria-labelledby")
+      return [] if attribute_present?(attrs_node, "title")
+      return [] if body_contains_erb_output?(element)
+      return [] if visible_text_in(element).length.positive?
+
+      [build_finding(:link_name, attrs_node, file, lines)]
+    end
+
+    def check_input(open_tag, file, lines)
+      type = (attribute_static_value(open_tag, "type") || "text").downcase
+      return [] if NON_INTERACTIVE_INPUT_TYPES.include?(type)
+      return [] if attribute_present?(open_tag, "aria-label") || attribute_present?(open_tag, "aria-labelledby")
+
+      id = attribute_static_value(open_tag, "id")
+      return [] if id && labeled_by_for?(id)
+
+      [build_finding(:input_label, open_tag, file, lines)]
+    end
+
+    def void_tag?(open_tag)
+      %w[img input].include?(open_tag_name(open_tag))
+    end
+
+    def open_tag_name(open_tag)
+      tok = open_tag.respond_to?(:tag_name) ? open_tag.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
+
+    def attribute_nodes(open_tag)
+      ErbParser.compact_children(open_tag).select { |c| c.is_a?(::Herb::AST::HTMLAttributeNode) }
+    end
+
+    def attribute_present?(open_tag, name)
+      attribute_nodes(open_tag).any? { |attr| attribute_name(attr) == name.downcase }
+    end
+
+    def attribute_name(attr)
+      name_wrapper, _ = ErbParser.compact_children(attr)
+      return nil unless name_wrapper
+
+      lit = ErbParser.compact_children(name_wrapper).first
+      return nil unless lit && lit.respond_to?(:content)
+
+      lit.content.respond_to?(:value) ? lit.content.value.to_s.downcase : lit.content.to_s.downcase
+    end
+
+    def attribute_static_value(open_tag, name)
+      attr = attribute_nodes(open_tag).find { |a| attribute_name(a) == name.downcase }
+      return nil unless attr
+
+      _name_wrapper, value_wrapper = ErbParser.compact_children(attr)
+      return nil unless value_wrapper
+
+      ErbParser.compact_children(value_wrapper).filter_map do |child|
+        next unless child.is_a?(::Herb::AST::LiteralNode)
+
+        c = child.content
+        c.respond_to?(:value) ? c.value.to_s : c.to_s
+      end.join
+    end
+
+    # Walks the element's body subtree (including nested elements) for
+    # `<%=` ERB output. Descendant-aware so that
+    # `<button><span><%= label %></span></button>` is recognized as
+    # wrapping ERB output and defers to helper_recommended — same
+    # behavior the previous regex provided.
+    def body_contains_erb_output?(element)
+      body_nodes = Array(element.respond_to?(:body) ? element.body : [])
+      body_nodes.any? { |child| descendant_has_erb_output?(child) }
+    end
+
+    def descendant_has_erb_output?(node)
+      return false if node.nil?
+
+      if node.is_a?(::Herb::AST::ERBContentNode)
+        opening = node.tag_opening
+        return (opening.respond_to?(:value) ? opening.value : opening.to_s) == "<%="
+      end
+
+      ErbParser.compact_children(node).any? { |child| descendant_has_erb_output?(child) }
+    end
+
+    # Concatenated visible text content from descendant HTMLTextNodes —
+    # walks the entire subtree, including text inside nested elements
+    # (`<button><span>Save</span></button>` returns "Save"). ERB nodes
+    # don't contribute; the dynamic-content case is handled separately
+    # by body_contains_erb_output?.
+    def visible_text_in(element)
+      text = +""
+      ErbParser.each_node(element).each do |node|
+        next unless node.is_a?(::Herb::AST::HTMLTextNode)
+
+        c = node.content
+        text << (c.respond_to?(:value) ? c.value.to_s : c.to_s)
+      end
+      text.strip
+    end
+
+    def labeled_by_for?(id)
+      @label_for_cache ||= collect_labels_for_ids
+      @label_for_cache.include?(id)
+    end
+
+    # Walk the AST once per file to collect every `<label>` element's
+    # `for` attribute value into a Set. Cached for the duration of one
+    # file's scan_file call so successive labeled_by_for? checks are O(1).
+    def collect_labels_for_ids
+      ids = Set.new
+      ErbParser.each_node(@current_document) do |node|
+        next unless node.is_a?(::Herb::AST::HTMLElementNode)
+        next unless element_tag_name(node) == "label"
+
+        v = attribute_static_value(node.open_tag, "for")
+        ids << v if v
+      end
+      ids
+    end
+
+    def build_finding(rule, node, file, lines)
+      line, column = ErbParser.start_position(node)
+      Finding.new(
+        rule: rule,
+        file: file.relative_path_from(@root).to_s,
+        line: line,
+        column: column,
+        snippet: lines[line - 1]&.chomp&.strip
+      )
+    end
+
+    def print_report(findings)
+      return if findings.empty?
+
+      @output.puts ""
+      noun = findings.length == 1 ? "issue" : "issues"
+      @output.puts "Guardrails a11y: #{findings.length} static #{noun} found"
+      findings.each do |f|
+        @output.puts "  [#{f.rule}] #{f.file}:#{f.line}:#{f.column}"
+        @output.puts "    #{f.snippet}"
+      end
+    end
+  end
+end

data/lib/guardrails/a11y_deep.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "set"
+
+module Guardrails
+  # Consumes axe-core JSON output and folds the findings into Guardrails'
+  # unified report. Distinct from `A11yAudit`, which runs static template
+  # checks (image_alt, button_name, etc.) without rendering.
+  #
+  # Why parse-only, no run: bundling axe-core means bundling Capybara +
+  # headless Chrome as runtime deps of a static-analysis gem — too heavy
+  # for users who don't run system tests. Instead, users run axe-core
+  # however they already do (axe-core-rspec, `npx @axe-core/cli`, a
+  # CDP-driven script) and pass the JSON output to Guardrails:
+  #
+  #     npx @axe-core/cli http://localhost:3000/ --save axe.json
+  #     AXE_JSON=axe.json bundle exec rake guardrails:audit
+  #
+  # The result is a single unified report — static findings from
+  # A11yAudit plus runtime findings from axe — with the same exit-code
+  # semantics as the rest of the audit.
+  class A11yDeep
+    Finding = Struct.new(:rule, :impact, :description, :help_url, :url, :selector, keyword_init: true) do
+      def to_h
+        super
+      end
+    end
+
+    # Impacts we treat as audit-failing. axe emits one of: minor, moderate,
+    # serious, critical (and sometimes nil for `incomplete` findings or
+    # custom rule packs). The 0.6.0 default is "any known non-nil impact
+    # fails" — covers axe's full impact ladder and aligns with the static
+    # a11y rules which all fail unconditionally. Findings with a nil/
+    # unknown impact do NOT fail by default; tighten per-call via
+    # `failing_impacts:` if your rule pack emits custom severities.
+    DEFAULT_FAILING_IMPACTS = %w[minor moderate serious critical].freeze
+
+    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS)
+      @input = input
+      @output = output
+      @failing_impacts = Set.new(failing_impacts.map(&:to_s))
+    end
+
+    def run
+      findings = parse_input
+      print_report(findings)
+      findings
+    end
+
+    # Parse axe-core JSON. Accepts either a single result object
+    # `{ "url": "...", "violations": [...] }` or an array of results
+    # (multi-page runs, what `axe-core/cli --save` produces). Returns
+    # a flat list of Finding structs.
+    def parse(payload)
+      pages = payload.is_a?(Array) ? payload : [payload]
+      pages.flat_map { |page| parse_page(page) }
+    end
+
+    def any_failing?(findings)
+      findings.any? { |f| @failing_impacts.include?(f.impact.to_s) }
+    end
+
+    private
+
+    def parse_input
+      raw = @input.is_a?(Hash) || @input.is_a?(Array) ? @input : JSON.parse(File.read(@input.to_s, encoding: Encoding::UTF_8))
+      parse(raw)
+    rescue Errno::ENOENT
+      @output.puts "Guardrails a11y (deep): #{@input} not found — skipping"
+      []
+    rescue JSON::ParserError => e
+      @output.puts "Guardrails a11y (deep): could not parse #{@input} — #{e.message}"
+      []
+    end
+
+    def parse_page(page)
+      return [] unless page.is_a?(Hash)
+
+      url = page["url"]
+      Array(page["violations"]).flat_map do |violation|
+        rule = violation["id"]
+        impact = violation["impact"]
+        description = violation["help"] || violation["description"]
+        help_url = violation["helpUrl"]
+        Array(violation["nodes"]).map do |node|
+          Finding.new(
+            rule: rule,
+            impact: impact,
+            description: description,
+            help_url: help_url,
+            url: url,
+            selector: Array(node["target"]).first
+          )
+        end
+      end
+    end
+
+    def print_report(findings)
+      return if findings.empty?
+
+      grouped = findings.group_by(&:url)
+      @output.puts ""
+      @output.puts "Guardrails a11y (deep): #{findings.length} finding#{'s' if findings.length != 1} from axe-core"
+
+      grouped.each do |url, page_findings|
+        @output.puts ""
+        @output.puts "  #{url || '(no url)'}"
+        page_findings.each do |f|
+          impact_label = f.impact ? "[#{f.impact}]" : "[unknown]"
+          selector = f.selector ? " (#{f.selector})" : ""
+          @output.puts "    #{impact_label} #{f.rule} — #{f.description}#{selector}"
+          @output.puts "      #{f.help_url}" if f.help_url
+        end
+      end
+    end
+  end
+end

data/lib/guardrails/audit/auto_fixer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../hex_normalizer"
+require_relative "../token_matcher"
+
+module Guardrails
+  class Audit
+    class AutoFixer
+      Result = Struct.new(:violation, :token, :kind, :distance, :replacement, keyword_init: true)
+
+      # Each violation type maps to the token syntaxes that can substitute
+      # for it in source. raw_color in a view attribute can only become
+      # var(--name); tailwind_arbitrary in a class string can only become
+      # a named utility derived from a Tailwind theme color.
+      COMPATIBLE_SYNTAX = {
+        raw_color: [:css_var],
+        tailwind_arbitrary: [:tailwind]
+      }.freeze
+
+      def initialize(root, output: $stdout, tokens: [], near_match_policy: "notify",
+                     near_match_threshold: TokenMatcher::NEAR_MATCH_THRESHOLD)
+        @root = Pathname(root)
+        @output = output
+        @near_match_policy = near_match_policy
+        @matchers = build_matchers(tokens, near_match_threshold)
+      end
+
+      def apply(violations)
+        applicable = violations.select { |v| applicable?(v) }
+        return [] if applicable.empty?
+
+        applied = applicable.group_by(&:file).flat_map do |file, file_violations|
+          process_file(@root.join(file), file_violations)
+        end
+
+        report(applied)
+        applied
+      end
+
+      def applicable?(violation)
+        !applicable_match(violation).nil?
+      end
+
+      private
+
+      def build_matchers(tokens, threshold)
+        COMPATIBLE_SYNTAX.transform_values do |syntaxes|
+          subset = tokens.select { |t| syntaxes.include?(t.syntax) }
+          TokenMatcher.new(subset, near_match_threshold: threshold)
+        end
+      end
+
+      def applicable_match(violation)
+        matcher = @matchers[violation.type]
+        return nil unless matcher
+
+        match = matcher.match(violation.value)
+        return nil unless match
+        return match if match.kind == :exact
+        return match if match.kind == :near && @near_match_policy == "fix"
+
+        nil
+      end
+
+      def process_file(path, violations)
+        return [] unless path.exist?
+
+        original = File.read(path, encoding: Encoding::UTF_8)
+        lines = original.lines
+        applied = []
+
+        violations.group_by(&:line).each do |line_num, line_violations|
+          line_idx = line_num - 1
+          next unless lines[line_idx]
+
+          line_violations.sort_by { |v| -v.column }.each do |v|
+            match = applicable_match(v)
+            next unless match
+
+            edit = build_edit(v, match, lines[line_idx])
+            next unless edit
+
+            start_idx, length, replacement = edit
+            lines[line_idx] = lines[line_idx][0...start_idx] + replacement + lines[line_idx][(start_idx + length)..]
+            applied << Result.new(
+              violation: v,
+              token: match.token,
+              kind: match.kind,
+              distance: match.distance,
+              replacement: replacement
+            )
+          end
+        end
+
+        new_content = lines.join
+        File.write(path, new_content, encoding: Encoding::UTF_8) if new_content != original
+        applied
+      end
+
+      # Returns [start_idx, length, replacement_string] for the in-line edit,
+      # or nil if the source no longer matches the violation's expected text.
+      def build_edit(violation, match, line)
+        case violation.type
+        when :raw_color
+          start_idx = violation.column - 1
+          length = violation.value.length
+          return nil unless line[start_idx, length] == violation.value
+
+          [start_idx, length, "var(--#{match.token.name})"]
+        when :tailwind_arbitrary
+          tailwind_edit(violation, match, line)
+        end
+      end
+
+      # For `bg-[#0066ff]`, walk back from the `[` to the start of the prefix
+      # (stopping at whitespace, quote, or `:` to preserve variants like
+      # `lg:hover:bg-[...]`), then replace the whole `prefix-[value]` span
+      # with `prefix-tokenname`.
+      def tailwind_edit(violation, match, line)
+        bracket_start = violation.column - 1
+        return nil unless line[bracket_start] == "["
+
+        bracket_end = line.index("]", bracket_start)
+        return nil unless bracket_end
+        return nil unless bracket_start.positive? && line[bracket_start - 1] == "-"
+
+        prefix_dash = bracket_start - 1
+        prefix_start = prefix_dash
+        prefix_start -= 1 while prefix_start.positive? && line[prefix_start - 1] !~ /[\s"':]/
+
+        prefix = line[prefix_start...prefix_dash]
+        return nil if prefix.empty?
+
+        full_length = bracket_end - prefix_start + 1
+        [prefix_start, full_length, "#{prefix}-#{match.token.name}"]
+      end
+
+      def report(applied)
+        return if applied.empty?
+
+        applied.group_by { |r| r.violation.type }.each do |type, results|
+          label = type == :raw_color ? "raw_color → CSS custom property" : "tailwind_arbitrary → named utility"
+          noun = results.length == 1 ? "fix" : "fixes"
+          @output.puts ""
+          @output.puts "Guardrails audit: applied #{results.length} auto-#{noun} (#{label})"
+          results.each do |r|
+            suffix = r.kind == :near ? " [NEAR MATCH, channel diff #{r.distance}]" : ""
+            @output.puts "  #{r.violation.file}:#{r.violation.line}  #{r.violation.value} → #{r.replacement}#{suffix}"
+          end
+        end
+      end
+    end
+  end
+end