Merge pull request #43 from github/accessibility/issues/1293/migrate-a11y-erblint-rules-a11y-landmark-has-label

Migrate accessibility rule `a11y_landmark_has_label` from dotcom to erblint-github

Author: Adrián Bolonio

README.md

@@ -33,6 +33,8 @@ linters:
     enabled: true
   GitHub::Accessibility::ImageHasAlt:
     enabled: true
+  GitHub::Accessibility::LandmarkHasLabelCounter:
+    enabled: true
   GitHub::Accessibility::LinkHasHrefCounter:
     enabled: true
   GitHub::Accessibility::NestedInteractiveElementsCounter:
@@ -55,6 +57,7 @@ linters:
 - [GitHub::Accessibility::AvoidGenericLinkTextCounter](./docs/rules/accessibility/avoid-generic-link-text-counter.md)
 - [GitHub::Accessibility::DisabledAttributeCounter](./docs/rules/accessibility/disabled-attribute-counter-test)
 - [GitHub::Accessibility::IframeHasTitle](./docs/rules/accessibility/iframe-has-title.md)
+- [GitHub::Accessibility::LandmarkHasLabelCounter](./docs/rules/accessibility/landmark-has-label-counter.md)
 - [GitHub::Accessibility::ImageHasAlt](./docs/rules/accessibility/image-has-alt.md)
 - [GitHub::Accessibility::LinkHasHrefCounter](./docs/rules/accessibility/link-has-href-counter.md)
 - [GitHub::Accessibility::NestedInteractiveElementsCounter](./docs/rules/accessibility/nested-interactive-elements-counter.md)

docs/rules/accessibility/landmark-has-label-counter.md

@@ -0,0 +1,28 @@
+# Landmark Has Label Counter
+
+## Rule Details
+
+Landmark elements should have an `aria-label` attribute, or `aria-labelledby` if a heading elements exists in the landmark.
+
+## Resources
+
+- [ARIA Landmarks Example](https://www.w3.org/WAI/ARIA/apg/example-index/landmarks/index.html)
+
+## Examples
+### **Incorrect** code for this rule 👎
+
+```erb
+<!-- incorrect -->
+<section>
+  <h1>This is a text</h1>
+</section>
+```
+
+### **Correct** code for this rule  👍
+
+```erb
+<!-- correct -->
+<section aria-labelledby="title_id"t>
+  <h1 id="title_id">This is a text</h1>
+</section>
+```

lib/erblint-github/linters/github/accessibility/landmark_has_label_counter.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../../custom_helpers"
+
+module ERBLint
+  module Linters
+    module GitHub
+      module Accessibility
+        class LandmarkHasLabelCounter < Linter
+          include ERBLint::Linters::CustomHelpers
+          include LinterRegistry
+
+          LANDMARK_ROLES = %w[complementary navigation region search].freeze
+          LANDMARK_TAGS = %w[aside nav section].freeze
+          MESSAGE = "Landmark elements should have an aria-label attribute, or aria-labelledby if a heading elements exists in the landmark."
+          ROLE_TAG_MAPPING = { "complementary" => "aside", "navigation" => "nav", "region" => "section" }.freeze
+
+          def get_additional_message(tag, roles)
+            role_matched = (roles & ROLE_TAG_MAPPING.keys).first
+            if role_matched
+              tag_matched = ROLE_TAG_MAPPING[role_matched]
+
+              if tag.name == tag_matched
+                "The <#{tag_matched}> element will automatically communicate a role of '#{role_matched}'. You can safely drop the role attribute."
+              else
+                replace_message = if tag.name == "div"
+                                    "If possible replace this tag with a <#{tag_matched}>."
+                                  else
+                                    "Wrapping this element in a <#{tag_matched}> and setting a label on it is reccomended."
+                                  end
+
+                "The <#{tag_matched}> element will automatically communicate a role of '#{role_matched}'. #{replace_message}"
+              end
+            elsif roles.include?("search") && tag.name != "form"
+              "The 'search' role works best when applied to a <form> element. If possible replace this tag with a <form>."
+            end
+          end
+
+          def run(processed_source)
+            tags(processed_source).each do |tag|
+              next if tag.closing?
+
+              possible_roles = possible_attribute_values(tag, "role")
+              next unless LANDMARK_TAGS.include?(tag.name) && (possible_roles & LANDMARK_ROLES).empty?
+              next if tag.attributes["aria-label"]&.value&.present? || tag.attributes["aria-labelledby"]&.value&.present?
+
+              message = get_additional_message(tag, possible_roles)
+              if message
+                generate_offense(self.class, processed_source, tag, "#{MESSAGE}\n#{message}")
+              else
+                generate_offense(self.class, processed_source, tag)
+              end
+            end
+
+            counter_correct?(processed_source)
+          end
+
+          def autocorrect(processed_source, offense)
+            return unless offense.context
+
+            lambda do |corrector|
+              if processed_source.file_content.include?("erblint:counter #{simple_class_name}")
+                # update the counter if exists
+                corrector.replace(offense.source_range, offense.context)
+              else
+                # add comment with counter if none
+                corrector.insert_before(processed_source.source_buffer.source_range, "#{offense.context}\n")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

test/linters/accessibility/landmark_has_label_counter_test.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class LandmarkHasLabelCounter < LinterTestCase
+  def linter_class
+    ERBLint::Linters::GitHub::Accessibility::LandmarkHasLabelCounter
+  end
+
+  def test_warns_if_landmark_has_no_label
+    @file = <<~ERB
+      <section>
+        <h1>This is a text</h1>
+      </section>
+    ERB
+    @linter.run(processed_source)
+
+    assert_equal(2, @linter.offenses.count)
+    error_messages = @linter.offenses.map(&:message).sort
+    assert_match(/If you must, add <%# erblint:counter GitHub::Accessibility::LandmarkHasLabelCounter 1 %> to bypass this check./, error_messages.first)
+    assert_match(/Landmark elements should have an aria-label attribute, or aria-labelledby if a heading elements exists in the landmark./, error_messages.last)
+  end
+
+  def test_does_not_warn_if_landmark_has_label
+    @file = <<~ERB
+      <section aria-labelledby="title_id"t>
+        <h1 id="title_id">This is a text</h1>
+      </section>
+    ERB
+    @linter.run(processed_source)
+
+    assert_empty @linter.offenses
+  end
+
+  def test_does_not_warn_if_landmark_has_label_and_has_correct_counter_comment
+    @file = <<~ERB
+      <%# erblint:counter GitHub::Accessibility::LandmarkHasLabelCounter 1 %>
+       <section>
+        <h1>This is a text</h1>
+      </section>
+    ERB
+    @linter.run(processed_source)
+
+    assert_equal 0, @linter.offenses.count
+  end
+
+  def test_does_not_autocorrect_when_ignores_are_correct
+    @file = <<~ERB
+      <%# erblint:counter GitHub::Accessibility::LandmarkHasLabelCounter 1 %>
+       <section>
+        <h1>This is a text</h1>
+      </section>
+    ERB
+
+    assert_equal @file, corrected_content
+  end
+
+  def test_does_autocorrect_when_ignores_are_not_correct
+    @file = <<~ERB
+      <%# erblint:counter GitHub::Accessibility::LandmarkHasLabelCounter 3 %>
+       <section>
+        <h1>This is a text</h1>
+      </section>
+    ERB
+    refute_equal @file, corrected_content
+
+    expected_content = <<~ERB
+      <%# erblint:counter GitHub::Accessibility::LandmarkHasLabelCounter 1 %>
+       <section>
+        <h1>This is a text</h1>
+      </section>
+    ERB
+    assert_equal expected_content, corrected_content
+  end
+end