a11y-lint 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1c92e880f51310dfe123ffdbc872bc661a781371365c53dd1a1972e302dcc1d
-  data.tar.gz: dfb7186f222b4c87ffdc818e843907435eebda8e99cccdc945cf1f4d8b77708f
+  metadata.gz: 7f62cdc346f6aa1f5c2cae674c365678a333479966aabd1b144e7901f90e7cdf
+  data.tar.gz: 874c7cb5bac0680cb58fb2f73e89304c21862686010f5b0e721aad19861c0bbb
 SHA512:
-  metadata.gz: 0fde7a03bb0e20294c451a57da6aa487fd7aa6cf6b3bde0d41e6b7a323ededf15c626e6b06e7dd55f37b109a0371cc24b5708fd5528f959bb96a6269642152f8
-  data.tar.gz: b43f87086fdabf16d139639d169be80cadea3da8c61b09e7a92cc66f4c5d59011dce8b7433307877b652b4b85c2d4cb923c6ed9a95695094b035cbcdbe2d6d0a
+  metadata.gz: 5757d27c00656b68b5b4209a153da09e720d190bacb5124e1860a03a53d3e0df4d02909a2c1d667c5be477394228274a6e64c95b4a032d64cb14a65ba72f5bd7
+  data.tar.gz: bf502097c82848041313039b29271808133c1ff3be50b1d8e4b31b5d7df7bb1c35bb1ae643b869143355bbcd3dd2cfcddf98acd44ac858f4edb436e5699b3b92

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-04-27
+
+### Added
+
+- `.a11y-lint.yml` now supports a top-level `hidden_wrapper_classes` list; content inside elements whose class matches is treated as hidden from assistive technology when the four accessible-name rules (`AnchorMissingAccessibleName`, `ButtonMissingAccessibleName`, `LinkToMissingAccessibleName`, `ButtonTagMissingAccessibleName`) determine whether a button/link has an accessible name. Opt-in; default is no filtering
+
 ## [0.11.0] - 2026-04-21
 
 ### Added

data/lib/a11y/lint/cli.rb

@@ -71,10 +71,10 @@ module A11y
       end
 
       def lint_files(files)
-        rules = all_rules
-        slim_runner = SlimRunner.new(rules)
-        erb_runner = ErbRunner.new(rules)
-        phlex_runner = PhlexRunner.new(rules)
+        configuration = load_configuration
+        slim_runner = SlimRunner.new(configuration:)
+        erb_runner = ErbRunner.new(configuration:)
+        phlex_runner = PhlexRunner.new(configuration:)
 
         files.flat_map do |file|
           source = File.read(file)
@@ -91,18 +91,8 @@ module A11y
         end
       end
 
-      def all_rules
-        configuration = Configuration.load(
-          @config_path,
-          search_path: @argv.first || "."
-        )
-
-        Rules.constants.filter_map do |name|
-          klass = Rules.const_get(name)
-          next unless klass.is_a?(Class) && klass < NodeRule
-
-          klass if configuration.enabled?(klass.rule_name)
-        end
+      def load_configuration
+        Configuration.load(@config_path, search_path: @argv.first || ".")
       end
 
       def print_results(offenses)

data/lib/a11y/lint/configuration.rb

@@ -41,6 +41,20 @@ module A11y
 
         @config.dig(rule_name, "Enabled") != false
       end
+
+      def hidden_wrapper_classes
+        @hidden_wrapper_classes ||=
+          Array(@config["hidden_wrapper_classes"]).map(&:to_s).freeze
+      end
+
+      def enabled_rules
+        Rules.constants.filter_map do |name|
+          klass = Rules.const_get(name)
+          next unless klass.is_a?(Class) && klass < NodeRule
+
+          klass if enabled?(klass.rule_name)
+        end
+      end
     end
   end
 end

data/lib/a11y/lint/erb_element_node.rb

@@ -5,12 +5,14 @@ module A11y
     # Wraps a Nokogiri HTML element from an ERB template
     # as a queryable node for lint rules.
     class ErbElementNode
-      attr_reader :line
+      attr_reader :line, :configuration
 
-      def initialize(nokogiri_node:, line:, has_erb_output: false)
+      def initialize(
+        nokogiri_node:, line:, configuration: Configuration.new
+      )
         @nokogiri_node = nokogiri_node
         @line = line
-        @has_erb_output = has_erb_output
+        @configuration = configuration
       end
 
       def tag_name
@@ -45,15 +47,58 @@ module A11y
       end
 
       def text_content?
-        @has_erb_output || !@nokogiri_node.text.strip.empty?
+        return false if hidden_wrapper?(@nokogiri_node)
+
+        visible_text_or_output?(@nokogiri_node)
       end
 
       # Returns direct element children wrapped as ErbElementNode objects.
+      # Excludes elements whose class attribute matches a configured
+      # hidden-wrapper class, since CSS-hidden subtrees do not contribute
+      # to the accessible name.
       def children
-        @nokogiri_node.element_children.map do |child|
-          ErbElementNode.new(nokogiri_node: child, line: child.line)
+        @nokogiri_node.element_children.filter_map do |child|
+          next if hidden_wrapper?(child)
+
+          ErbElementNode.new(
+            nokogiri_node: child, line: child.line,
+            configuration: configuration
+          )
+        end
+      end
+
+      private
+
+      def visible_text_or_output?(node)
+        return false if hidden_wrapper?(node)
+        return true if own_text_or_marker?(node)
+
+        node.element_children.any? { |c| visible_text_or_output?(c) }
+      end
+
+      def own_text_or_marker?(node)
+        node.children.any? do |c|
+          next false unless c.text?
+
+          content = c.content
+          content.include?(ErbRunner::ERB_OUTPUT_MARKER) ||
+            !content.strip.empty?
         end
       end
+
+      def hidden_wrapper?(node)
+        classes = configuration.hidden_wrapper_classes
+        return false if classes.empty?
+
+        node_classes(node).any? { |klass| classes.include?(klass) }
+      end
+
+      def node_classes(node)
+        return [] unless node.respond_to?(:attributes)
+
+        value = node.attributes["class"]&.value
+        value.is_a?(String) ? value.split : []
+      end
     end
   end
 end

data/lib/a11y/lint/erb_runner.rb

@@ -14,8 +14,9 @@ module A11y
         link meta param source track wbr
       ].freeze
 
-      def initialize(rules)
-        @rules = rules
+      def initialize(rules = nil, configuration: Configuration.new)
+        @rules = rules || configuration.enabled_rules
+        @configuration = configuration
       end
 
       def run(source, filename:)
@@ -30,7 +31,7 @@ module A11y
 
       private
 
-      attr_reader :rules
+      attr_reader :rules, :configuration
 
       def check_html_nodes(source)
         html = source.gsub(ERB_OUTPUT_TAG, ERB_OUTPUT_MARKER)
@@ -50,7 +51,7 @@ module A11y
         ErbElementNode.new(
           nokogiri_node: nokogiri_node,
           line: nokogiri_node.line,
-          has_erb_output: nokogiri_node.text.include?(ERB_OUTPUT_MARKER)
+          configuration: configuration
         )
       end
 
@@ -88,10 +89,53 @@ module A11y
         return [nil, false] unless end_match
 
         block_content = rest[0...end_match.begin(0)]
-        codes = block_content.scan(ERB_OUTPUT_TAG).map { |m| m[0].strip }
-        text_only = block_content.gsub(ERB_TAG, "").strip
+        visible_codes_and_text(block_content)
+      end
+
+      # Returns [visible_codes, visible_non_output_text?] where "visible"
+      # means not inside a hidden-wrapper element (per configuration).
+      def visible_codes_and_text(block_content)
+        indexed_codes = []
+        html = indexed_marker_html(block_content, indexed_codes)
+        fragment = Nokogiri::HTML4::DocumentFragment.parse(html)
+        strip_hidden_wrappers!(fragment)
+
+        remaining = fragment.to_html
+        visible_codes = indexed_codes.each_with_index.filter_map do |code, i|
+          code if remaining.include?("#{ERB_OUTPUT_MARKER}#{i}_")
+        end
+        [visible_codes, non_marker_text?(remaining)]
+      end
+
+      def indexed_marker_html(block_content, codes)
+        block_content.gsub(ERB_OUTPUT_TAG) do
+          codes << Regexp.last_match(1).strip
+          "#{ERB_OUTPUT_MARKER}#{codes.length - 1}_"
+        end.gsub(ERB_TAG, "")
+      end
+
+      def non_marker_text?(html)
+        !html.gsub(/#{ERB_OUTPUT_MARKER}\d+_/, "").strip.empty?
+      end
+
+      def strip_hidden_wrappers!(node)
+        return if configuration.hidden_wrapper_classes.empty?
+
+        node.element_children.each do |child|
+          if hidden_wrapper_element?(child)
+            child.remove
+          else
+            strip_hidden_wrappers!(child)
+          end
+        end
+      end
+
+      def hidden_wrapper_element?(node)
+        value = node.attributes["class"]&.value
+        return false unless value.is_a?(String)
 
-        [codes, !text_only.empty?]
+        classes = configuration.hidden_wrapper_classes
+        value.split.any? { |klass| classes.include?(klass) }
       end
 
       def check_node(node)

data/lib/a11y/lint/phlex_node.rb

@@ -13,6 +13,7 @@ module A11y
         :block_body_codes,
         :call_node,
         :children,
+        :configuration,
         :line,
         :tag_name
       )
@@ -23,7 +24,8 @@ module A11y
         call_node: nil, children: [],
         block_body_codes: nil,
         block_has_text_children: false,
-        text_content: false
+        text_content: false,
+        configuration: Configuration.new
       )
         @tag_name = tag_name
         @attributes = attributes
@@ -33,6 +35,7 @@ module A11y
         @block_body_codes = block_body_codes
         @block_has_text_children = block_has_text_children
         @text_content = text_content
+        @configuration = configuration
       end
       # rubocop:enable Metrics/ParameterLists
 
@@ -52,30 +55,46 @@ module A11y
         @text_content
       end
 
-      def self.build_tag(call_node, children: [], text_content: false)
+      def self.build_tag(
+        call_node, children: [], text_content: false,
+        configuration: Configuration.new
+      )
         name = call_node.name.to_s
         new(
           tag_name: html_tag_name(name),
           attributes: extract_attributes(call_node),
           line: call_node.location.start_line,
           children: children,
-          text_content: text_content
+          text_content: text_content,
+          configuration: configuration
         )
       end
 
       def self.build_helper(
         call_node,
         block_body_codes: nil,
-        block_has_text_children: false
+        block_has_text_children: false,
+        configuration: Configuration.new
       )
         new(
           call_node: CallNode.new(call_node),
           line: call_node.location.start_line,
           block_body_codes: block_body_codes,
-          block_has_text_children: block_has_text_children
+          block_has_text_children: block_has_text_children,
+          configuration: configuration
         )
       end
 
+      def self.kwarg_class_values(call_node)
+        return [] unless call_node.arguments
+
+        value = kwarg_nodes(call_node).find do |elem|
+          kwarg_key(elem.key) == "class"
+        end&.value
+
+        value.is_a?(Prism::StringNode) ? value.unescaped.split : []
+      end
+
       def self.extract_attributes(call_node)
         return {} unless call_node.arguments
 

data/lib/a11y/lint/phlex_runner.rb

@@ -9,8 +9,9 @@ module A11y
     class PhlexRunner
       PHLEX_PATTERN = /\bdef\s+view_template\b/
 
-      def initialize(rules)
-        @rules = rules
+      def initialize(rules = nil, configuration: Configuration.new)
+        @rules = rules || configuration.enabled_rules
+        @configuration = configuration
       end
 
       def run(source, filename:)
@@ -26,7 +27,7 @@ module A11y
 
       private
 
-      attr_reader :rules
+      attr_reader :rules, :configuration
 
       def walk(node)
         if receiverless_call?(node)
@@ -48,7 +49,12 @@ module A11y
         children = collect_block_children(node.block)
         has_text = tag_block_has_text?(node.block, children)
         check_node(
-          PhlexNode.build_tag(node, children:, text_content: has_text)
+          PhlexNode.build_tag(
+            node,
+            children: children,
+            text_content: has_text,
+            configuration: configuration
+          )
         )
       end
 
@@ -57,7 +63,8 @@ module A11y
         helper = PhlexNode.build_helper(
           node,
           block_body_codes: codes,
-          block_has_text_children: has_text
+          block_has_text_children: has_text,
+          configuration: configuration
         )
         check_node(helper)
         walk_block(node.block)
@@ -85,10 +92,24 @@ module A11y
         kids = collect_block_children(child.block)
         has_text = tag_block_has_text?(child.block, kids)
         tag = PhlexNode.build_tag(
-          child, children: kids, text_content: has_text
+          child, children: kids, text_content: has_text,
+                 configuration: configuration
         )
-        result << tag
         check_node(tag)
+        result << tag unless hidden_wrapper_tag?(child)
+      end
+
+      def hidden_wrapper_tag?(call_node)
+        classes = configuration.hidden_wrapper_classes
+        return false if classes.empty?
+
+        tag_class_values(call_node).any? { |klass| classes.include?(klass) }
+      end
+
+      def tag_class_values(call_node)
+        return [] unless call_node.arguments
+
+        PhlexNode.kwarg_class_values(call_node)
       end
 
       def tag_block_has_text?(block, children)
@@ -114,8 +135,10 @@ module A11y
       end
 
       # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
       def scan_block_content(node, codes)
         node.child_nodes.compact.each do |child|
+          next if tag_call?(child) && hidden_wrapper_tag?(child)
           return true if child.is_a?(Prism::YieldNode)
           return true if tag_call?(child) && child.block
           next if tag_call?(child)
@@ -125,6 +148,7 @@ module A11y
         false
       end
       # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
 
       def walk_block(block)
         return unless block.is_a?(Prism::BlockNode)

data/lib/a11y/lint/slim_node.rb

@@ -6,11 +6,12 @@ module A11y
     class SlimNode
       include BlockInspection
 
-      attr_reader :line
+      attr_reader :line, :configuration
 
-      def initialize(sexp, line:)
+      def initialize(sexp, line:, configuration: Configuration.new)
         @sexp = sexp
         @line = line
+        @configuration = configuration
       end
 
       def tag_name
@@ -90,6 +91,7 @@ module A11y
 
       def collect_output_codes(sexp)
         return [] unless sexp.is_a?(Array)
+        return [] if hidden_wrapper_sexp?(sexp)
         return [sexp[3]] if slim_output_sexp?(sexp)
 
         sexp.flat_map { |child| collect_output_codes(child) }
@@ -101,6 +103,7 @@ module A11y
 
       def block_text_content?(sexp)
         return false unless sexp.is_a?(Array)
+        return false if hidden_wrapper_sexp?(sexp)
         return true if slim_text_sexp?(sexp) || html_tag_sexp?(sexp)
 
         sexp.any? { |child| block_text_content?(child) }
@@ -108,18 +111,69 @@ module A11y
 
       def text_or_output?(sexp)
         return false unless sexp.is_a?(Array)
+        return false if hidden_wrapper_sexp?(sexp)
         return true if slim_text_sexp?(sexp) || slim_output_sexp?(sexp)
 
         sexp.any? { |child| text_or_output?(child) }
       end
 
+      def hidden_wrapper_sexp?(sexp)
+        return false unless html_tag_sexp?(sexp)
+        return false if configuration.hidden_wrapper_classes.empty?
+
+        class_values(sexp[3]).any? do |klass|
+          configuration.hidden_wrapper_classes.include?(klass)
+        end
+      end
+
+      def class_values(attrs_sexp)
+        return [] unless attrs_sexp.is_a?(Array) &&
+                         attrs_sexp[0] == :html && attrs_sexp[1] == :attrs
+
+        attrs_sexp[2..].flat_map { |attr| class_values_for_attr(attr) }
+      end
+
+      def class_values_for_attr(attr)
+        return [] unless attr.is_a?(Array) &&
+                         attr[0] == :html && attr[1] == :attr &&
+                         attr[2] == "class"
+
+        value = static_class_string(attr[3])
+        value ? value.split : []
+      end
+
+      # Extracts a static class string from the two forms Slim emits:
+      # `[:static, "name"]` for class shortcuts (`.popover`) and
+      # `[:escape, true, [:slim, :interpolate, "name"]]` for `class="..."`.
+      def static_class_string(value_sexp)
+        return unless value_sexp.is_a?(Array)
+        return static_sexp_value(value_sexp) if value_sexp[0] == :static
+
+        interpolate_sexp_value(value_sexp)
+      end
+
+      def static_sexp_value(sexp)
+        sexp[1] if sexp[1].is_a?(String)
+      end
+
+      def interpolate_sexp_value(sexp)
+        return unless sexp[0] == :escape && sexp[2].is_a?(Array)
+        return unless sexp[2][0] == :slim && sexp[2][1] == :interpolate
+
+        sexp[2][2] if sexp[2][2].is_a?(String)
+      end
+
       def slim_text_sexp?(sexp)
         sexp[0] == :slim && sexp[1] == :text
       end
 
       def collect_children(sexp)
         return [] unless sexp.is_a?(Array)
-        return [SlimNode.new(sexp, line: @line)] if html_tag_sexp?(sexp)
+
+        if html_tag_sexp?(sexp)
+          return [SlimNode.new(sexp, line: @line, configuration: configuration)]
+        end
+
         return collect_children(sexp[3]) if slim_control_sexp?(sexp)
         return [] unless sexp[0] == :multi
 

data/lib/a11y/lint/slim_runner.rb

@@ -4,8 +4,9 @@ module A11y
   module Lint
     # Parses Slim templates and checks them against accessibility rules.
     class SlimRunner
-      def initialize(rules)
-        @rules = rules
+      def initialize(rules = nil, configuration: Configuration.new)
+        @rules = rules || configuration.enabled_rules
+        @configuration = configuration
       end
 
       def run(source, filename:)
@@ -22,13 +23,13 @@ module A11y
 
       private
 
-      attr_reader(:rules)
+      attr_reader(:rules, :configuration)
 
       def walk(sexp)
         return unless node?(sexp)
 
         @line += 1 if sexp[0] == :newline
-        new_node = SlimNode.new(sexp, line: @line)
+        new_node = SlimNode.new(sexp, line: @line, configuration:)
         check_node(new_node) if html_tag?(sexp) || slim_output?(sexp)
         @line += continuation_newlines(sexp)
         sexp.each { |child| walk(child) }

data/lib/a11y/lint/version.rb

@@ -2,6 +2,6 @@
 
 module A11y
   module Lint
-    VERSION = "0.11.0"
+    VERSION = "0.12.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: a11y-lint
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Abdullah Hashim