rails_accessibility_testing 1.5.8 → 1.6.0

data/lib/rails_accessibility_testing/checks/interactive_elements_check.rb

@@ -6,6 +6,12 @@ module RailsAccessibilityTesting
     #
     # WCAG 2.1 AA: 2.4.4 Link Purpose (Level A), 4.1.2 Name, Role, Value (Level A)
     #
+    # @note Links with href="#":
+    #   - Only flags anchors with href="#" that have NO accessible name
+    #   - An accessible name can be: visible text, aria-label, or aria-labelledby
+    #   - Links with href="#" that have visible text or ARIA attributes are valid and NOT flagged
+    #   - This avoids false positives for valid anchor links that use href="#" with proper labeling
+    #
     # @api private
     class InteractiveElementsCheck < BaseCheck
       def self.rule_name
@@ -45,6 +51,7 @@ module RailsAccessibilityTesting
           aria_label = element[:"aria-label"]
           aria_labelledby = element[:"aria-labelledby"]
           title = element[:title]
+          href = element[:href]
           
           # Check if element contains ERB placeholder (for static scanning)
           # ErbExtractor replaces <%= ... %> with "ERB_CONTENT" so we can detect it
@@ -68,12 +75,24 @@ module RailsAccessibilityTesting
           aria_labelledby_empty = aria_labelledby.nil? || aria_labelledby.to_s.strip.empty?
           title_empty = title.nil? || title.to_s.strip.empty?
           
+          # Only report violation if element has no accessible name
+          # For links with href="#", we only flag if they have no text AND no aria-label AND no aria-labelledby
+          # Links with href="#" that have visible text or ARIA attributes are valid and should not be flagged
           if text_empty && aria_label_empty && aria_labelledby_empty && title_empty && !has_image_with_alt
             element_ctx = element_context(element)
             tag = element.tag_name
             
+            # Special message for empty links with href="#"
+            # This rule correctly detects anchors with href="#" that have no accessible name,
+            # but avoids false positives when they have visible text or aria-label/aria-labelledby
+            message = if tag == 'a' && (href == '#' || href.to_s.strip == '#')
+              "Link missing accessible name [href: #]"
+            else
+              "#{tag.capitalize} missing accessible name"
+            end
+            
             violations << violation(
-              message: "#{tag.capitalize} missing accessible name",
+              message: message,
               element_context: element_ctx,
               wcag_reference: tag == 'a' ? "2.4.4" : "4.1.2",
               remediation: generate_remediation(tag, element_ctx)

data/lib/rails_accessibility_testing/composed_page_scanner.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require_relative 'view_composition_builder'
+require_relative 'erb_extractor'
+
+module RailsAccessibilityTesting
+  # Scans a complete composed page (layout + view + partials) for heading hierarchy
+  # This ensures heading hierarchy is checked across the entire page, not just individual files
+  #
+  # @api private
+  class ComposedPageScanner
+    def initialize(view_file)
+      @view_file = view_file
+      @builder = ViewCompositionBuilder.new(view_file)
+    end
+
+    # Scan the complete composed page for heading hierarchy violations
+    # @return [Hash] Hash with :errors and :warnings arrays
+    def scan_heading_hierarchy
+      return { errors: [], warnings: [] } unless @view_file && File.exist?(@view_file)
+
+      # Build composition
+      all_files = @builder.build
+      return { errors: [], warnings: [] } if all_files.empty?
+
+      # Get all headings from complete composition
+      headings = @builder.all_headings
+      return { errors: [], warnings: [] } if headings.empty?
+
+      violations = []
+
+      # Check 1: Missing H1
+      h1_count = headings.count { |h| h[:level] == 1 }
+      first_heading = headings.first
+
+      if h1_count == 0
+        if first_heading
+          violations << create_violation(
+            message: "Page has h#{first_heading[:level]} but no h1 heading (checked complete page: layout + view + partials)",
+            heading: first_heading,
+            wcag_reference: "1.3.1",
+            remediation: "Add an <h1> heading to your page. The H1 can be in the layout, view, or a partial:\n\n<h1>Main Page Title</h1>"
+          )
+        else
+          violations << create_violation(
+            message: "Page missing H1 heading (checked complete page: layout + view + partials)",
+            heading: nil,
+            wcag_reference: "1.3.1",
+            remediation: "Add an <h1> heading to your page. The H1 can be in the layout, view, or a partial:\n\n<h1>Main Page Title</h1>"
+          )
+        end
+      end
+
+      # Check 2: Multiple H1s
+      if h1_count > 1
+        h1_headings = headings.select { |h| h[:level] == 1 }
+        h1_headings[1..-1].each do |h1|
+          violations << create_violation(
+            message: "Page has multiple h1 headings (#{h1_count} total) - only one h1 should be used per page (checked complete page: layout + view + partials)",
+            heading: h1,
+            wcag_reference: "1.3.1",
+            remediation: "Use only one <h1> per page. Convert additional h1s to h2 or lower:\n\n<h1>Main Title</h1>\n<h2>Section Title</h2>"
+          )
+        end
+      end
+
+      # Check 3: Heading hierarchy skipped levels
+      # Only flag if we're skipping from a real heading (not from h0)
+      # If the first heading is h2, that's fine - it just means no h1 exists (handled by Check 1)
+      previous_level = nil
+      headings.each do |heading|
+        current_level = heading[:level]
+        if previous_level && current_level > previous_level + 1
+          # Only flag if we're skipping from a real heading level
+          violations << create_violation(
+            message: "Heading hierarchy skipped (h#{previous_level} to h#{current_level}) - checked complete page: layout + view + partials",
+            heading: heading,
+            wcag_reference: "1.3.1",
+            remediation: "Fix the heading hierarchy. Don't skip levels. Use h#{previous_level + 1} instead of h#{current_level}."
+          )
+        end
+        previous_level = current_level
+      end
+
+      # Convert to errors/warnings format (matching ViolationConverter format)
+      errors = violations.map do |v|
+        {
+          type: v[:message],
+          element: {
+            tag: v[:heading] ? "h#{v[:heading][:level]}" : 'page',
+            text: v[:heading] ? v[:heading][:text] : 'Page-level heading hierarchy check',
+            file: v[:file] || @view_file
+          },
+          file: v[:file] || @view_file,
+          line: v[:line] || 1,
+          wcag: v[:wcag_reference],
+          remediation: v[:remediation],
+          page_level_check: true,
+          check_type: 'heading_hierarchy'
+        }
+      end
+
+      { errors: errors, warnings: [] }
+    end
+    
+    # Scan the complete composed page for all heading issues (not just hierarchy)
+    # This includes: empty headings, styling-only headings, etc.
+    # @return [Hash] Hash with :errors and :warnings arrays
+    def scan_all_headings
+      return { errors: [], warnings: [] } unless @view_file && File.exist?(@view_file)
+      
+      # Build composition
+      all_files = @builder.build
+      return { errors: [], warnings: [] } if all_files.empty?
+      
+      # Get all headings from complete composition
+      headings = @builder.all_headings
+      return { errors: [], warnings: [] } if headings.empty?
+      
+      errors = []
+      warnings = []
+      
+      # Check for empty headings (across complete page)
+      headings.each do |heading|
+        heading_text = heading[:text]
+        
+        # Check if heading contains ERB placeholder
+        has_erb_content = heading_text.include?('ERB_CONTENT')
+        
+        # Check if heading is empty or only contains whitespace
+        if (heading_text.empty? || heading_text.match?(/^\s*$/)) && !has_erb_content
+          errors << {
+            type: "Empty heading detected (<h#{heading[:level]}>) - headings must have accessible text (checked complete page: layout + view + partials)",
+            element: {
+              tag: "h#{heading[:level]}",
+              text: 'Empty heading',
+              file: heading[:file]
+            },
+            file: heading[:file],
+            line: heading[:line],
+            wcag: "4.1.2",
+            remediation: "Add descriptive text to the heading:\n\n<h#{heading[:level]}>Descriptive Heading Text</h#{heading[:level]}>",
+            page_level_check: true,
+            check_type: 'heading_empty'
+          }
+        end
+        
+        # Check for styling-only headings (very short or generic text)
+        if heading_text.length <= 2 && heading_text.match?(/^[•→…\s\-_=]+$/)
+          warnings << {
+            type: "Heading appears to be used for styling only (text: '#{heading_text}') - headings should be descriptive (checked complete page: layout + view + partials)",
+            element: {
+              tag: "h#{heading[:level]}",
+              text: heading_text,
+              file: heading[:file]
+            },
+            file: heading[:file],
+            line: heading[:line],
+            wcag: "2.4.6",
+            remediation: "Use CSS for styling instead of headings. Replace with a <div> or <span> with appropriate CSS classes.",
+            page_level_check: true,
+            check_type: 'heading_styling'
+          }
+        end
+      end
+      
+      { errors: errors, warnings: warnings }
+    end
+    
+    # Scan the complete composed page for duplicate IDs
+    # IDs must be unique across the entire page (layout + view + partials)
+    # @return [Hash] Hash with :errors and :warnings arrays
+    def scan_duplicate_ids
+      return { errors: [], warnings: [] } unless @view_file && File.exist?(@view_file)
+      
+      # Build composition
+      all_files = @builder.build
+      return { errors: [], warnings: [] } if all_files.empty?
+      
+      # Collect all IDs from complete composition
+      id_map = {} # id => [{ file: String, line: Integer, element: String }]
+      
+      all_files.each do |file|
+        # Handle both relative and absolute paths
+        file_path = if File.exist?(file)
+          file
+        elsif defined?(Rails) && Rails.root
+          rails_path = Rails.root.join(file)
+          rails_path.exist? ? rails_path.to_s : nil
+        else
+          nil
+        end
+        next unless file_path && File.exist?(file_path)
+        
+        content = File.read(file_path)
+        html_content = ErbExtractor.extract_html(content)
+        doc = Nokogiri::HTML::DocumentFragment.parse(html_content)
+        
+        # Find all elements with IDs
+        doc.css('[id]').each do |element|
+          id = element[:id]
+          next if id.nil? || id.to_s.strip.empty?
+          # Skip ERB_CONTENT placeholder - it's not a real ID
+          next if id == 'ERB_CONTENT'
+          # Skip IDs that contain ERB_CONTENT - these are dynamic IDs that can't be statically verified
+          # Example: "collection_answers_ERB_CONTENT_ERB_CONTENT_" - the actual IDs will be different at runtime
+          # because the ERB expressions will evaluate to different values
+          next if id.include?('ERB_CONTENT')
+          
+          id_map[id] ||= []
+          line = find_line_number_for_element(content, element)
+          id_map[id] << {
+            file: file_path,  # Use resolved path
+            line: line,
+            element: element.name
+          }
+        end
+      end
+      
+      errors = []
+      
+      # Find duplicate IDs
+      id_map.each do |id, occurrences|
+        if occurrences.length > 1
+          # Report all occurrences after the first one
+          occurrences[1..-1].each do |occurrence|
+            errors << {
+              type: "Duplicate ID '#{id}' found (checked complete page: layout + view + partials) - IDs must be unique across the entire page",
+              element: {
+                tag: occurrence[:element],
+                id: id,
+                file: occurrence[:file]
+              },
+              file: occurrence[:file],
+              line: occurrence[:line],
+              wcag: "4.1.1",
+              remediation: "Remove or rename the duplicate ID. Each ID must be unique on the page:\n\n<!-- Change one of these -->\n<div id=\"#{id}\">...</div>\n<div id=\"#{id}\">...</div>\n\n<!-- To -->\n<div id=\"#{id}\">...</div>\n<div id=\"#{id}-2\">...</div>",
+              page_level_check: true,
+              check_type: 'duplicate_ids'
+            }
+          end
+        end
+      end
+      
+      { errors: errors, warnings: [] }
+    end
+    
+    # Helper to find line number for an element
+    def find_line_number_for_element(content, element)
+      tag_name = element.name
+      id = element[:id]
+      
+      lines = content.split("\n")
+      lines.each_with_index do |line, index|
+        if line.include?("<#{tag_name}") && (id.nil? || line.include?("id=\"#{id}\"") || line.include?("id='#{id}'"))
+          return index + 1
+        end
+      end
+      
+      1
+    end
+    
+    # Scan the complete composed page for ARIA landmarks
+    # This ensures landmarks in layout are detected when scanning view files
+    # @return [Hash] Hash with :errors and :warnings arrays
+    def scan_aria_landmarks
+      return { errors: [], warnings: [] } unless @view_file && File.exist?(@view_file)
+      
+      # Build composition
+      all_files = @builder.build
+      return { errors: [], warnings: [] } if all_files.empty?
+      
+      # Check for main landmark across all files
+      has_main = false
+      main_location = nil
+      
+      all_files.each do |file|
+        next unless File.exist?(file)
+        
+        content = File.read(file)
+        html_content = ErbExtractor.extract_html(content)
+        doc = Nokogiri::HTML::DocumentFragment.parse(html_content)
+        
+        # Check for <main> tag or [role="main"]
+        main_elements = doc.css('main, [role="main"]')
+        if main_elements.any?
+          has_main = true
+          main_location = file
+          break
+        end
+      end
+      
+      warnings = []
+      
+      # Only report missing main if it's truly missing from the complete page
+      unless has_main
+        warnings << {
+          type: "Page missing MAIN landmark (checked complete page: layout + view + partials)",
+          element: {
+            tag: 'page',
+            text: 'Page-level ARIA landmark check'
+          },
+          file: @view_file,
+          line: 1,
+          wcag: "1.3.1",
+          remediation: "Add a <main> landmark to your page. It can be in the layout, view, or a partial:\n\n<main id=\"maincontent\">\n  <!-- Page content -->\n</main>",
+          page_level_check: true,
+          check_type: 'aria_landmarks'
+        }
+      end
+      
+      { errors: [], warnings: warnings }
+    end
+
+    private
+
+    def create_violation(message:, heading:, wcag_reference:, remediation:)
+      {
+        message: message,
+        file: heading ? heading[:file] : @view_file,
+        line: heading ? heading[:line] : 1,
+        wcag_reference: wcag_reference,
+        remediation: remediation,
+        heading: heading  # Keep heading info for element context
+      }
+    end
+  end
+end
+

data/lib/rails_accessibility_testing/config/yaml_loader.rb

@@ -84,7 +84,8 @@ module RailsAccessibilityTesting
           merged_system_specs = base_system_specs.merge(profile_system_specs)
           
           base_config.merge(
-            'enabled' => profile_config.fetch('enabled', base_config.fetch('enabled', true)),  # Profile can override enabled, default to true
+            # Support both 'accessibility_enabled' (new) and 'enabled' (legacy) for backward compatibility
+            'accessibility_enabled' => profile_config.fetch('accessibility_enabled', profile_config.fetch('enabled', base_config.fetch('accessibility_enabled', base_config.fetch('enabled', true)))),  # Profile can override, supports legacy 'enabled' key
             'checks' => merged_checks,
             'summary' => merged_summary,
             'scan_strategy' => profile_config['scan_strategy'] || base_config['scan_strategy'] || 'paths',
@@ -123,7 +124,7 @@ module RailsAccessibilityTesting
         # Default configuration when no file exists
         def default_config
           {
-            'enabled' => true,  # Global enable/disable flag for all accessibility checks
+            'accessibility_enabled' => true,  # Global enable/disable flag for all accessibility checks
             'wcag_level' => 'AA',
             'checks' => default_checks,
             'summary' => {

data/lib/rails_accessibility_testing/erb_extractor.rb

@@ -4,6 +4,12 @@ module RailsAccessibilityTesting
   # Extracts HTML from ERB templates by converting Rails helpers to HTML
   # This allows static analysis of view files without rendering them
   #
+  # @note ERB and ID handling:
+  #   - Dynamic IDs like "collection_answers_<%= question.id %>_<%= option.id %>_" are preserved
+  #   - ERB expressions are replaced with "ERB_CONTENT" placeholder to maintain structure
+  #   - This ensures IDs like "collection_answers_ERB_CONTENT_ERB_CONTENT_" are not collapsed
+  #   - Labels with matching ERB structure will also have "ERB_CONTENT" and can be matched
+  #
   # @api private
   class ErbExtractor
     # Convert ERB template to HTML for static analysis
@@ -26,8 +32,57 @@ module RailsAccessibilityTesting
 
     private
 
+    # Convert raw HTML elements that have ERB in their attributes
+    # This handles cases like: <input id="collection_answers_<%= question.id %>_<%= option.id %>_">
+    # We need to preserve the structure of dynamic IDs so they don't get collapsed
+    # 
+    # @note This must run BEFORE remove_erb_tags to preserve ERB structure in attributes
+    def convert_raw_html_with_erb
+      # Handle input elements (checkbox, radio, text, etc.) with ERB in attributes
+      # Pattern: <input ... id="...<%= ... %>..." ... />
+      @content.gsub!(/<input\s+([^>]*?)>/i) do |match|
+        attrs = $1
+        # Replace ERB in attributes with placeholder, preserving structure
+        # This ensures "id='collection_answers_<%= question.id %>_<%= option.id %>_'" 
+        # becomes "id='collection_answers_ERB_CONTENT_ERB_CONTENT_'"
+        attrs_with_placeholders = attrs.gsub(/<%=(.*?)%>/m, 'ERB_CONTENT')
+        "<input #{attrs_with_placeholders}>"
+      end
+      
+      # Handle label_tag with string interpolation in first argument: <%= label_tag "collection_answers_#{question.id}_#{option.id}_", option.value %>
+      # This handles string interpolation like "collection_answers_#{question.id}_#{option.id}_"
+      # Must match BEFORE the simple string pattern
+      @content.gsub!(/<%=\s*label_tag\s+["']([^"']*#\{[^}]+\}[^"']*)["'],\s*([^,]+)(?:,\s*[^%]*)?%>/) do
+        id_template = $1
+        text_expr = $2
+        # Replace Ruby interpolation with placeholder
+        id_with_placeholder = id_template.gsub(/#\{[^}]+\}/, 'ERB_CONTENT')
+        # Handle text expression - could be a variable, string, or method call
+        text_placeholder = if text_expr.strip.match?(/^["']/)
+          # It's a string literal
+          text_expr.strip.gsub(/^["']|["']$/, '')
+        else
+          # It's a variable or method call - will produce content at runtime
+          'ERB_CONTENT'
+        end
+        "<label for=\"#{id_with_placeholder}\">#{text_placeholder}</label>"
+      end
+      
+      # Handle label_tag helper with simple string: <%= label_tag "id_string", "text", options %>
+      # Pattern: label_tag "id_string", "text", options
+      @content.gsub!(/<%=\s*label_tag\s+["']([^"']+)["'],\s*["']?([^"']*?)["']?[^%]*%>/) do
+        id = $1
+        text = $2
+        # Replace ERB in id string with placeholder (if any)
+        id_with_placeholder = id.gsub(/<%=(.*?)%>/m, 'ERB_CONTENT')
+        "<label for=\"#{id_with_placeholder}\">#{text}</label>"
+      end
+    end
+
     # Convert Rails helpers to placeholder HTML
     def convert_rails_helpers
+      # First, handle raw HTML elements with ERB in attributes (before removing ERB tags)
+      convert_raw_html_with_erb
       convert_form_helpers
       convert_image_helpers
       convert_link_helpers

data/lib/rails_accessibility_testing/rspec_integration.rb

@@ -52,7 +52,8 @@ module RailsAccessibilityTesting
           require 'rails_accessibility_testing/config/yaml_loader'
           profile = defined?(Rails) && Rails.env.test? ? :test : :development
           config = Config::YamlLoader.load(profile: profile)
-          enabled = config.fetch('enabled', true)  # Default to enabled if not specified
+          # Support both 'accessibility_enabled' (new) and 'enabled' (legacy) for backward compatibility
+          enabled = config.fetch('accessibility_enabled', config.fetch('enabled', true))  # Default to enabled if not specified
           !enabled  # Return true if disabled
         rescue StandardError
           false  # If config can't be loaded, assume enabled

data/lib/rails_accessibility_testing/static_file_scanner.rb

@@ -36,7 +36,8 @@ module RailsAccessibilityTesting
       # Check if accessibility checks are globally disabled
       begin
         config = Config::YamlLoader.load(profile: :test)
-        enabled = config.fetch('enabled', true)
+        # Support both 'accessibility_enabled' (new) and 'enabled' (legacy) for backward compatibility
+        enabled = config.fetch('accessibility_enabled', config.fetch('enabled', true))
         return { errors: [], warnings: [] } unless enabled
       rescue StandardError
         # If config can't be loaded, continue (assume enabled)
@@ -70,14 +71,56 @@ module RailsAccessibilityTesting
         # Run all enabled checks using existing RuleEngine
         violations = engine.check(static_page, context: context)
 
-        # Convert violations to errors/warnings format with line numbers
+        # For page-level checks, use composed page scanner
+        # This checks the complete page (layout + view + partials) for:
+        # - All heading checks (hierarchy, empty, styling-only)
+        # - ARIA landmarks (main, etc.)
+        # - Duplicate IDs (must be unique across entire page)
+        require_relative 'composed_page_scanner'
+        composed_scanner = ComposedPageScanner.new(@view_file)
+        hierarchy_result = composed_scanner.scan_heading_hierarchy
+        all_headings_result = composed_scanner.scan_all_headings
+        landmarks_result = composed_scanner.scan_aria_landmarks
+        duplicate_ids_result = composed_scanner.scan_duplicate_ids
+        
+        # Filter out page-level violations from regular violations
+        # (we'll use the composed page scanner results instead)
+        heading_violations = violations.select { |v| 
+          v.rule_name.to_s == 'heading'
+        }
+        landmarks_violations = violations.select { |v| 
+          v.rule_name.to_s == 'aria_landmarks' &&
+          (v.message.include?('missing MAIN') || v.message.include?('missing main') || 
+           v.message.include?('MAIN landmark')) 
+        }
+        duplicate_ids_violations = violations.select { |v|
+          v.rule_name.to_s == 'duplicate_ids'
+        }
+        other_violations = violations.reject { |v| 
+          heading_violations.include?(v) || landmarks_violations.include?(v) || duplicate_ids_violations.include?(v)
+        }
+        
+        # Convert non-page-level violations to errors/warnings format
         line_number_finder = LineNumberFinder.new(@file_content)
-        ViolationConverter.convert(
-          violations,
+        result = ViolationConverter.convert(
+          other_violations,
           view_file: @view_file,
           line_number_finder: line_number_finder,
           config: config
         )
+        
+        # Add composed page results (all heading checks + landmarks + duplicate IDs)
+        result[:errors] = (result[:errors] || []) + 
+                         hierarchy_result[:errors] + 
+                         all_headings_result[:errors] + 
+                         duplicate_ids_result[:errors]
+        result[:warnings] = (result[:warnings] || []) + 
+                          hierarchy_result[:warnings] + 
+                          all_headings_result[:warnings] + 
+                          landmarks_result[:warnings] + 
+                          duplicate_ids_result[:warnings]
+        
+        result
       rescue StandardError => e
         # If engine fails, log error and return empty results
         if defined?(Rails) && Rails.env.development?

data/lib/rails_accessibility_testing/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module RailsAccessibilityTesting
-  VERSION = "1.5.8"
+  VERSION = "1.6.0"
 end