a11y-lint 0.8.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0d462b5e30cff7f4b1c5adaa3eeb9d2ac1a1aa9d3dad477b1841e38e271f22a
-  data.tar.gz: 66d8731b7371b98e4fede0445536d994fcd3405721dfb0617f1c139bd5fce925
+  metadata.gz: e1c92e880f51310dfe123ffdbc872bc661a781371365c53dd1a1972e302dcc1d
+  data.tar.gz: dfb7186f222b4c87ffdc818e843907435eebda8e99cccdc945cf1f4d8b77708f
 SHA512:
-  metadata.gz: 6459a600d8cbd2465d5a9096eb99e36f319d1576cc685273b78505c636c15f77590104eec89ff4142d6525f70d5fc861822837fdf55cca9ed1afbad9a20011b5
-  data.tar.gz: 3c22904b9d168f559b9bc83522e1a5422fad6f2dd3d5beffd158ad06135ef6dacc85fdf3d832970b330ed1f4fd25c68a41b3bd8a34ef57ca6df8c2211a694dca
+  metadata.gz: 0fde7a03bb0e20294c451a57da6aa487fd7aa6cf6b3bde0d41e6b7a323ededf15c626e6b06e7dd55f37b109a0371cc24b5708fd5528f959bb96a6269642152f8
+  data.tar.gz: b43f87086fdabf16d139639d169be80cadea3da8c61b09e7a92cc66f4c5d59011dce8b7433307877b652b4b85c2d4cb923c6ed9a95695094b035cbcdbe2d6d0a

data/.claude/rules/testing.md

@@ -49,4 +49,4 @@ globs: test/**/*.rb
 
   Each style must be tested for both the offense case and the "passes with fix" case.
 
-- Every rule must be tested against both the Slim and ERB pipelines.
+- Every rule must be tested against the Slim, ERB, and Phlex pipelines.

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.3
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -13,6 +13,12 @@ Layout/LineLength:
     - "a11y-lint.gemspec"
 
 Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/AbcSize:
   Exclude:
     - "test/**/*"
 

data/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.11.0] - 2026-04-21
+
+### Added
+
+- `AreaMissingAlt` rule: detects `<area>` tags without `alt` attributes (WCAG 1.1.1)
+- `InputImageMissingAlt` rule: detects `<input type="image">` tags without `alt` attributes (WCAG 1.1.1)
+- `ImageSubmitTagMissingAlt` rule: detects `image_submit_tag` calls without an `alt` option (WCAG 1.1.1)
+- `InputMissingAutocomplete` rule: detects `<input>` elements without an `autocomplete` attribute (WCAG 1.3.5)
+- `AnchorMissingAccessibleName` rule: detects `<a>` elements without text content, `aria-label`, or a child image with `alt` (WCAG 4.1.2)
+- `ButtonMissingAccessibleName` rule: detects `<button>` elements without text content, `aria-label`, or a child image with `alt` (WCAG 4.1.2)
+
+### Changed
+
+- **Breaking:** Split `MissingAccessibleName` into `LinkToMissingAccessibleName` (for `link_to`/`external_link_to`) and `ButtonTagMissingAccessibleName` (for `button_tag`) to follow one-rule-per-helper convention
+- **Breaking:** Rename `A11y::Lint::Rule` to `A11y::Lint::NodeRule`. Custom rules that subclass the base class must update the parent class name
+- Auto-require all rule files instead of listing them individually
+- Node attribute storage now preserves string values, enabling rules to check attribute values (not just existence)
+
+### Fixed
+
+- `LinkToMissingAccessibleName` / `ButtonTagMissingAccessibleName`: no longer flag `link_to`/`button_tag` blocks containing an `image_tag` with a non-empty `alt` option
+
+## [0.10.0] - 2026-04-15
+
+### Changed
+
+- Introduce `A11y::Lint::CallNode` wrapper so rules express accessibility logic, not AST traversal
+- Expose Prism `CallNode` from `SlimNode` and `ErbNode` via the new `RubyCode` parser
+- Expose Prism `CallNode` from `PhlexNode` instead of converting to string
+- Extract Phlex HTML tag constants into `PhlexTags` module
+
+## [0.9.0] - 2026-04-15
+
+### Changed
+
+- **Breaking:** Require Ruby >= 3.3.0 (was 3.1.0). Prism ships with Ruby 3.3+ as a bundled gem
+- **Breaking:** `slim` is now an optional dependency. Add `gem "slim"` to your Gemfile if you lint `.slim` files. A `SlimLoadError` is raised with a helpful message if the gem is missing
+- `prism` is no longer a declared dependency (bundled with Ruby 3.3+)
+- Replace Ripper with Prism for Ruby code parsing in `ImageTagMissingAlt` and `MissingAccessibleName` rules
+- Custom error classes are now defined in `lib/a11y/lint/errors.rb`
+
+### Fixed
+
+- `MissingAccessibleName`: fix false positive when block contains visible text or HTML tags (e.g. `link_to do` with a `span` or plain text inside)
+- Add `block_body_codes` and `block_has_text_children?` to all three node types (Slim, ERB, Phlex) so block content inspection works across all pipelines
+
 ## [0.8.0] - 2026-04-14
 
 ### Added

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-a11y-lint is a Ruby gem (v0.1.0) for accessibility linting. It uses the `A11y::Lint` module namespace. Requires Ruby >= 3.1.0.
+a11y-lint is a Ruby gem (v0.1.0) for accessibility linting. It uses the `A11y::Lint` module namespace. Requires Ruby >= 3.3.0.
 
 ## Commands
 
@@ -24,15 +24,26 @@ a11y-lint is a Ruby gem (v0.1.0) for accessibility linting. It uses the `A11y::L
 - **Slim pipeline:** `SlimRunner` parses Slim templates via `Slim::Parser`; `SlimNode` wraps Slim S-expressions
 - **ERB pipeline:** `ErbRunner` parses ERB templates via Nokogiri; `ErbNode` wraps Nokogiri nodes and extracted `<%= %>` Ruby code
 - **Phlex pipeline:** `PhlexRunner` parses Phlex view classes via Prism; `PhlexNode` wraps Prism AST call nodes; detects Phlex files by the presence of `def view_template`
+- **Ruby code parsing:** `RubyCode` (`lib/a11y/lint/ruby_code.rb`) — parses a Ruby code string once with Prism and exposes the resulting `CallNode`; used by `SlimNode` and `ErbNode` so rules work against a parsed AST instead of re-parsing strings
 - **Configuration:** `lib/a11y/lint/configuration.rb` — loads `.a11y-lint.yml` to enable/disable individual rules; searches upward from the target path
-- **Rules:** `lib/a11y/lint/rules/` — organized by WCAG principle (`perceivable/`, `operable/`, `understandable/`, `robust/`); rules implement `check(node)` against the shared node interface (`tag_name`, `attribute?`, `attributes`, `ruby_code`, `line`)
+- **Rules:** `lib/a11y/lint/rules/` — organized by WCAG principle (`perceivable/`, `operable/`, `understandable/`, `robust/`); rules implement `check(node)` against the shared node interface (`tag_name`, `attribute?`, `attributes`, `call_node`, `line`)
 - **Version:** `lib/a11y/lint/version.rb`
 - **Type signatures (RBS):** `sig/a11y/lint.rbs`
 - **Tests:** `test/` directory using Minitest; test helper at `test/test_helper.rb`
 - **Dummy app:** `test/fixtures/dummy_app/` — a fixture app with Slim/ERB/Phlex templates for end-to-end smoke testing before releases (`bundle exec a11y-lint test/fixtures/dummy_app`)
 
+## Rule Scoping Convention
+
+Each rule targets **one element or helper**, unless multiple elements share identical check logic (e.g., `<ul>` and `<ol>` in `ListInvalidChildren`).
+
+- **HTML element rules** are named after the element: `ImgMissingAlt`, `AreaMissingAlt`, `AnchorMissingAccessibleName`
+- **Rails helper rules** are named after the helper: `ImageTagMissingAlt`, `LinkToMissingAccessibleName`
+- HTML/helper pairs mirror each other (e.g., `ImgMissingAlt` / `ImageTagMissingAlt`)
+
+Do not bundle unrelated elements or helpers into a single rule just because they share a WCAG criterion.
+
 ## Code Style
 
 RuboCop is configured in `.rubocop.yml`:
-- Target Ruby version: 3.1
+- Target Ruby version: 3.3
 - Enforces double quotes for strings

data/lib/a11y/lint/block_inspection.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module A11y
+  module Lint
+    # Shared block-content queries for node types.
+    # Depends on the host class implementing
+    # #block_has_text_children? and #block_body_codes.
+    module BlockInspection
+      ICON_HELPERS = %w[inline_svg icon svg_icon].freeze
+
+      def block_has_only_icon_helpers?
+        return false if block_has_text_children?
+
+        codes = block_body_codes
+        return true unless codes&.any?
+
+        codes.all? do |code|
+          icon_helper?(code) || decorative_image_tag?(code)
+        end
+      end
+
+      private
+
+      def icon_helper?(code)
+        call = RubyCode.new(code).call_node
+        call && ICON_HELPERS.include?(call.method_name)
+      end
+
+      # image_tag counts as decorative only when it lacks a non-empty
+      # alt. A non-empty alt provides the accessible name, matching how
+      # <a><img alt="Home"></a> is treated by
+      # AnchorMissingAccessibleName#child_image_has_alt?.
+      def decorative_image_tag?(code)
+        call = RubyCode.new(code).call_node
+        call &&
+          call.method_name == "image_tag" &&
+          !call.keyword_non_empty?(:alt)
+      end
+    end
+  end
+end

data/lib/a11y/lint/call_node.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module A11y
+  module Lint
+    # Wraps a Prism::CallNode with a rule-friendly query API.
+    class CallNode
+      attr_reader :prism_node
+
+      def initialize(prism_node)
+        @prism_node = prism_node
+      end
+
+      def method_name
+        @prism_node.name.to_s
+      end
+
+      # Checks for a keyword argument by name.
+      #   keyword?(:alt)          => alt: or "alt" =>
+      #   keyword?(:aria, :label) => aria: { label: ... }
+      #   keyword?(:"aria-label") => "aria-label" =>
+      def keyword?(*keys)
+        return false unless (kw_hash = find_keyword_hash)
+
+        if keys.length == 1
+          flat_keyword?(kw_hash, keys[0])
+        else
+          nested_keyword?(kw_hash, keys[0], keys[1])
+        end
+      end
+
+      # True when the keyword is present AND its value is a non-empty
+      # string literal OR any non-string expression (dynamic — can't be
+      # statically proven empty, so treat as providing content).
+      # False when the key is absent or the value is an empty string
+      # literal.
+      def keyword_non_empty?(key)
+        return false unless (kw_hash = find_keyword_hash)
+
+        assoc = kw_hash.elements.find { |a| key_name(a) == key.to_s }
+        return false unless assoc
+
+        value = assoc.value
+        return !value.unescaped.empty? if value.is_a?(Prism::StringNode)
+
+        true
+      end
+
+      def positional_args
+        return [] unless @prism_node.arguments
+
+        @prism_node.arguments.arguments.reject do |a|
+          a.is_a?(Prism::KeywordHashNode)
+        end
+      end
+
+      def first_positional_arg_empty_string?
+        first = positional_args.first
+        first.is_a?(Prism::StringNode) && first.unescaped.empty?
+      end
+
+      def block?
+        !@prism_node.block.nil?
+      end
+
+      # Finds a receiverless call by method name in this node's
+      # subtree (including self). Returns a CallNode or nil.
+      def find(name)
+        found = search_for_call(@prism_node, name)
+        found ? self.class.new(found) : nil
+      end
+
+      private
+
+      def flat_keyword?(kw_hash, key)
+        kw_hash.elements.any? do |assoc|
+          key_name(assoc) == key.to_s
+        end
+      end
+
+      def nested_keyword?(kw_hash, outer_key, inner_key)
+        assoc = kw_hash.elements.find do |a|
+          key_name(a) == outer_key.to_s
+        end
+        return false unless assoc&.value.is_a?(Prism::HashNode)
+
+        assoc.value.elements.any? do |inner|
+          key_name(inner) == inner_key.to_s
+        end
+      end
+
+      def find_keyword_hash
+        return unless @prism_node.arguments
+
+        @prism_node.arguments.arguments.find do |arg|
+          arg.is_a?(Prism::KeywordHashNode)
+        end
+      end
+
+      def key_name(assoc)
+        return unless assoc.is_a?(Prism::AssocNode)
+
+        case assoc.key
+        when Prism::SymbolNode then assoc.key.unescaped
+        when Prism::StringNode then assoc.key.unescaped
+        end
+      end
+
+      def search_for_call(node, name)
+        if node.is_a?(Prism::CallNode) &&
+           node.receiver.nil? &&
+           node.name.to_s == name
+          return node
+        end
+
+        node.child_nodes.compact.each do |child|
+          found = search_for_call(child, name)
+          return found if found
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/a11y/lint/cli.rb

@@ -4,8 +4,7 @@ require "optparse"
 
 module A11y
   module Lint
-    # Command-line interface for running accessibility
-    # linting on Slim templates.
+    # Command-line interface for running accessibility linting.
     class CLI
       def initialize(argv, stdout: $stdout, stderr: $stderr)
         @argv = argv
@@ -100,7 +99,7 @@ module A11y
 
         Rules.constants.filter_map do |name|
           klass = Rules.const_get(name)
-          next unless klass.is_a?(Class) && klass < Rule
+          next unless klass.is_a?(Class) && klass < NodeRule
 
           klass if configuration.enabled?(klass.rule_name)
         end

data/lib/a11y/lint/erb_element_node.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module A11y
+  module Lint
+    # Wraps a Nokogiri HTML element from an ERB template
+    # as a queryable node for lint rules.
+    class ErbElementNode
+      attr_reader :line
+
+      def initialize(nokogiri_node:, line:, has_erb_output: false)
+        @nokogiri_node = nokogiri_node
+        @line = line
+        @has_erb_output = has_erb_output
+      end
+
+      def tag_name
+        @nokogiri_node.name
+      end
+
+      def attribute?(name)
+        attributes.key?(name)
+      end
+
+      def attributes
+        @attributes ||=
+          @nokogiri_node
+          .attributes
+          .transform_values(&:value)
+      end
+
+      def call_node
+        nil
+      end
+
+      def ruby_code
+        nil
+      end
+
+      def block_body_codes
+        nil
+      end
+
+      def block_has_text_children?
+        false
+      end
+
+      def text_content?
+        @has_erb_output || !@nokogiri_node.text.strip.empty?
+      end
+
+      # Returns direct element children wrapped as ErbElementNode objects.
+      def children
+        @nokogiri_node.element_children.map do |child|
+          ErbElementNode.new(nokogiri_node: child, line: child.line)
+        end
+      end
+    end
+  end
+end

data/lib/a11y/lint/erb_output_node.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module A11y
+  module Lint
+    # Wraps an extracted ERB output tag (<%= ... %>)
+    # as a queryable node for lint rules.
+    class ErbOutputNode
+      include BlockInspection
+
+      attr_reader(:block_body_codes, :line, :ruby_code)
+
+      def initialize(
+        ruby_code:, line:,
+        block_body_codes: nil, block_has_text_children: false
+      )
+        @ruby_code = ruby_code
+        @line = line
+        @block_body_codes = block_body_codes
+        @block_has_text_children = block_has_text_children
+      end
+
+      def tag_name
+        nil
+      end
+
+      def attribute?(name)
+        attributes.key?(name)
+      end
+
+      def attributes
+        {}
+      end
+
+      def call_node
+        @call_node ||= RubyCode.new(ruby_code).call_node
+      end
+
+      def block_has_text_children?
+        @block_has_text_children
+      end
+
+      def children
+        []
+      end
+    end
+  end
+end

data/lib/a11y/lint/erb_runner.rb

@@ -8,6 +8,7 @@ module A11y
     class ErbRunner
       ERB_TAG = /<%.*?%>/m
       ERB_OUTPUT_TAG = /<%=\s*(.*?)\s*-?%>/m
+      ERB_OUTPUT_MARKER = "A11Y_LINT_ERB_OUTPUT"
       VOID_ELEMENTS = %w[
         area base br col embed hr img input
         link meta param source track wbr
@@ -32,19 +33,27 @@ module A11y
       attr_reader :rules
 
       def check_html_nodes(source)
-        html = source.gsub(ERB_TAG, "")
+        html = source.gsub(ERB_OUTPUT_TAG, ERB_OUTPUT_MARKER)
+        html = html.gsub(ERB_TAG, "")
         doc = Nokogiri::HTML4::DocumentFragment.parse(html)
 
         doc.traverse do |nokogiri_node|
           next unless nokogiri_node.element?
           next unless source_confirmed_element?(html, nokogiri_node.name)
 
-          check_node(
-            ErbNode.new(nokogiri_node: nokogiri_node, line: nokogiri_node.line)
-          )
+          node = build_erb_element_node(nokogiri_node)
+          check_node(node)
         end
       end
 
+      def build_erb_element_node(nokogiri_node)
+        ErbElementNode.new(
+          nokogiri_node: nokogiri_node,
+          line: nokogiri_node.line,
+          has_erb_output: nokogiri_node.text.include?(ERB_OUTPUT_MARKER)
+        )
+      end
+
       def source_confirmed_element?(html, tag_name)
         VOID_ELEMENTS.include?(tag_name) || html.include?("</#{tag_name}>")
       end
@@ -53,12 +62,38 @@ module A11y
         source.scan(ERB_OUTPUT_TAG) do
           match = Regexp.last_match
           code = match[1]
-          line_number = source[0...match.begin(0)].count("\n") + 1
-          node = ErbNode.new(ruby_code: code, line: line_number)
-          check_node(node)
+          line = source[0...match.begin(0)].count("\n") + 1
+          check_node(
+            build_erb_output_node(source, code, line, match.end(0))
+          )
         end
       end
 
+      def build_erb_output_node(source, code, line, match_end)
+        block_body_codes, block_has_text =
+          extract_block_info(source, code, match_end)
+
+        ErbOutputNode.new(
+          ruby_code: code, line: line,
+          block_body_codes: block_body_codes,
+          block_has_text_children: block_has_text
+        )
+      end
+
+      def extract_block_info(source, code, match_end)
+        return [nil, false] unless code.match?(/\s+do\s*\z/)
+
+        rest = source[match_end..]
+        end_match = rest.match(/<%-?\s*end\s*-?%>/m)
+        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
+
+        [codes, !text_only.empty?]
+      end
+
       def check_node(node)
         rules.each do |rule_class|
           message = rule_class.check(node)

data/lib/a11y/lint/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module A11y
+  module Lint
+    class Error < StandardError; end
+
+    # Raised when slim is not installed.
+    class SlimLoadError < Error
+      def initialize
+        super(
+          "a11y-lint needs the `slim` gem to lint .slim files. " \
+          "Add `gem \"slim\"` to your Gemfile."
+        )
+      end
+    end
+  end
+end

data/lib/a11y/lint/{rule.rb → node_rule.rb}

@@ -2,8 +2,8 @@
 
 module A11y
   module Lint
-    # Base class for accessibility lint rules.
-    class Rule
+    # Base class for per-node accessibility lint rules.
+    class NodeRule
       def self.check(node)
         new(node).check
       end
@@ -19,6 +19,10 @@ module A11y
       def check
         raise NotImplementedError
       end
+
+      private
+
+      attr_reader(:node)
     end
   end
 end