a11y-lint 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '041558922708cbcbc98072a22a57ee9c01292eabefc08d7c8ad2e289b89f159c'
-  data.tar.gz: b6de899716228d66c4a56a33e26e6dc2e55aa216e6a261ae82cef3f7c010b5a0
+  metadata.gz: 6fe6daf54c27923c7bb8d7c200baab018d5643ae6d17f1da3116b90b8b9a9b1a
+  data.tar.gz: 866c2a9cdbeddc1d8b4c726e89a104b4b193070fb52ec1ae45c6552fee41afe1
 SHA512:
-  metadata.gz: d7792835cc5123bc0832ca308ab88e28e51662f6ea1fc597458a5fcd96145e7135d9ad01c486f6efe6436b8f7453f44c8ef4f086bf76d6de7b8fdba271c122d4
-  data.tar.gz: 2d22327769cc721c03056845c6f13e46ef35a62b265b67114d5dc85eb6f8c656b1bcc3cf3d5d4e7a52fcde4fb7a2de25972ce822006fda0d78f558ade625aa68
+  metadata.gz: 1d07bed9bdc71ef0d08f6aa097c5c2550988c11899106e0ceeaaaf54a2c5243449842dd20390b321fdbbcf54811bc53a1487cbb502ac75698224dec99e13599c
+  data.tar.gz: a7ef305af11a87604e4f95ca3cfd62afa7c142601d9c081ec2448747414fef7ae32a11020134cebaddb4954c788eec5688251d18332d7079d8b531f98015ab6f

data/.rubocop.yml

@@ -7,6 +7,15 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
+Layout/LineLength:
+  Max: 80
+  Exclude:
+    - "a11y-lint.gemspec"
+
 Metrics/ClassLength:
   Exclude:
     - "test/**/*"
+
+Metrics/MethodLength:
+  Exclude:
+    - "test/**/*"

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-04-13
+
+### Fixed
+
+- Slim runner: correct line numbers in templates with multiline backslash continuations
+
+## [0.7.0] - 2026-04-13
+
+### Added
+
+- `ListInvalidChildren` rule: detects invalid direct children of `<ul>` and `<ol>` elements (WCAG 1.3.1)
+- `MissingAccessibleName` rule: consolidates `LinkMissingAccessibleName` into a single rule covering `link_to`, `external_link_to`, and `button_tag`
+- Per-rule configuration via `.a11y-lint.yml` file: enable or disable individual rules
+  - Place `.a11y-lint.yml` in the project root for automatic detection
+  - Use `--config PATH` to specify a custom configuration file path
+
+### Removed
+
+- `LinkMissingAccessibleName` rule: replaced by `MissingAccessibleName`
+
 ## [0.6.0] - 2026-03-31
 
 ### Added

data/CLAUDE.md

@@ -23,10 +23,12 @@ a11y-lint is a Ruby gem (v0.1.0) for accessibility linting. It uses the `A11y::L
 - **Entry point:** `lib/a11y/lint.rb` — defines the `A11y::Lint` module and `A11y::Lint::Error` exception
 - **Slim pipeline:** `SlimRunner` parses Slim templates via `Slim::Parser`; `Node` wraps Slim S-expressions
 - **ERB pipeline:** `ErbRunner` parses ERB templates via Nokogiri; `ErbNode` wraps Nokogiri nodes and extracted `<%= %>` Ruby code
-- **Rules:** `lib/a11y/lint/rules/` — rules implement `check(node)` against the shared node interface (`tag_name`, `attribute?`, `attributes`, `ruby_code`, `line`)
+- **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`)
 - **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 templates for end-to-end smoke testing before releases (`bundle exec a11y-lint test/fixtures/dummy_app`)
 
 ## Code Style
 

data/README.md

@@ -39,6 +39,26 @@ With no arguments, it scans the current directory recursively for `.slim` and `.
 a11y-lint
 ```
 
+### Configuration
+
+Create a `.a11y-lint.yml` file in your project root to enable or disable individual rules:
+
+```yaml
+ImgMissingAlt:
+  Enabled: false
+
+ImageTagMissingAlt:
+  Enabled: true
+```
+
+Rules not listed in the file are enabled by default. The linter searches for `.a11y-lint.yml` starting from the target directory and walking up to the filesystem root.
+
+To specify a config file explicitly:
+
+```bash
+a11y-lint --config path/to/.a11y-lint.yml app/views/
+```
+
 ### Ruby API
 
 ```ruby

data/lib/a11y/lint/cli.rb

@@ -4,12 +4,14 @@ require "optparse"
 
 module A11y
   module Lint
-    # Command-line interface for running accessibility linting on Slim templates.
+    # Command-line interface for running accessibility
+    # linting on Slim templates.
     class CLI
       def initialize(argv, stdout: $stdout, stderr: $stderr)
         @argv = argv
         @stdout = stdout
         @stderr = stderr
+        @config_path = nil
       end
 
       def run
@@ -42,6 +44,10 @@ module A11y
             exit 0
           end
 
+          opts.on("-c", "--config PATH", "Path to configuration file") do |path|
+            @config_path = path
+          end
+
           opts.on("-h", "--help", "Show help") do
             @stdout.puts(opts)
             exit 0
@@ -78,9 +84,16 @@ module A11y
       end
 
       def all_rules
+        configuration = Configuration.load(
+          @config_path,
+          search_path: @argv.first || "."
+        )
+
         Rules.constants.filter_map do |name|
           klass = Rules.const_get(name)
-          klass.new if klass.is_a?(Class) && klass < Rule
+          next unless klass.is_a?(Class) && klass < Rule
+
+          klass if configuration.enabled?(klass.rule_name)
         end
       end
 

data/lib/a11y/lint/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module A11y
+  module Lint
+    # Loads and stores rule configuration from a YAML file.
+    class Configuration
+      DEFAULT_FILE = ".a11y-lint.yml"
+
+      def initialize(config_hash = {})
+        @config = config_hash
+      end
+
+      def self.load(path = nil, search_path: Dir.pwd)
+        path ||= find_config_file(search_path)
+        return new unless path && File.exist?(path)
+
+        config_hash = YAML.safe_load_file(path) || {}
+        new(config_hash)
+      end
+
+      def self.find_config_file(start_dir)
+        dir = File.expand_path(start_dir)
+        dir = File.dirname(dir) unless File.directory?(dir)
+
+        loop do
+          candidate = File.join(dir, DEFAULT_FILE)
+          return candidate if File.exist?(candidate)
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+      private_class_method :find_config_file
+
+      def enabled?(rule_name)
+        return true unless @config.key?(rule_name)
+
+        @config.dig(rule_name, "Enabled") != false
+      end
+    end
+  end
+end

data/lib/a11y/lint/erb_node.rb

@@ -2,7 +2,8 @@
 
 module A11y
   module Lint
-    # Wraps a Nokogiri node or extracted ERB output tag as a queryable node for lint rules.
+    # Wraps a Nokogiri node or extracted ERB output tag
+    # as a queryable node for lint rules.
     class ErbNode
       attr_reader :line
 
@@ -28,13 +29,24 @@ module A11y
         @ruby_code_string
       end
 
+      # Returns direct element children wrapped as ErbNode objects.
+      def children
+        return [] unless @nokogiri_node
+
+        @nokogiri_node.element_children.map do |child|
+          ErbNode.new(nokogiri_node: child, line: child.line)
+        end
+      end
+
       private
 
       def extract_attributes
         return {} unless @nokogiri_node
 
-        @nokogiri_node.attributes.each_with_object({}) do |(name, _attr), result|
-          result[name] = true
+        @nokogiri_node
+          .attributes
+          .each_with_object({}) do |(name, _attr), result|
+            result[name] = true
         end
       end
     end

data/lib/a11y/lint/erb_runner.rb

@@ -34,7 +34,10 @@ module A11y
         doc.traverse do |nokogiri_node|
           next unless nokogiri_node.element?
 
-          node = ErbNode.new(nokogiri_node: nokogiri_node, line: nokogiri_node.line)
+          node = ErbNode.new(
+            nokogiri_node: nokogiri_node,
+            line: nokogiri_node.line
+          )
           check_node(node)
         end
       end
@@ -50,12 +53,12 @@ module A11y
       end
 
       def check_node(node)
-        rules.each do |rule|
-          message = rule.check(node)
+        rules.each do |rule_class|
+          message = rule_class.check(node)
           next unless message
 
           @offenses << Offense.new(
-            rule: rule.name,
+            rule: rule_class.rule_name,
             filename: @filename,
             line: node.line,
             message: message

data/lib/a11y/lint/node.rb

@@ -29,8 +29,40 @@ module A11y
         @attributes ||= extract_attributes
       end
 
+      # Returns direct HTML element children as Node objects.
+      # Walks through [:multi] and [:slim, :control] wrappers so that tags
+      # nested inside control flow are still treated as direct children.
+      # Opaque [:slim, :output] blocks are skipped.
+      def children
+        return [] unless html_tag?
+
+        body = @sexp[4]
+        collect_children(body)
+      end
+
       private
 
+      def html_tag?
+        @sexp[0] == :html && @sexp[1] == :tag
+      end
+
+      def collect_children(sexp)
+        return [] unless sexp.is_a?(Array)
+        return [Node.new(sexp, line: @line)] if html_tag_sexp?(sexp)
+        return collect_children(sexp[3]) if slim_control_sexp?(sexp)
+        return [] unless sexp[0] == :multi
+
+        sexp[1..].flat_map { |c| collect_children(c) }
+      end
+
+      def html_tag_sexp?(sexp)
+        sexp[0] == :html && sexp[1] == :tag
+      end
+
+      def slim_control_sexp?(sexp)
+        sexp[0] == :slim && sexp[1] == :control
+      end
+
       def extract_attributes
         return {} unless html_attributes?
 

data/lib/a11y/lint/rule.rb

@@ -4,11 +4,19 @@ module A11y
   module Lint
     # Base class for accessibility lint rules.
     class Rule
-      def name
-        self.class.name.split("::").last
+      def self.check(node)
+        new(node).check
       end
 
-      def check(node)
+      def self.rule_name
+        name.split("::").last
+      end
+
+      def initialize(node)
+        @node = node
+      end
+
+      def check
         raise NotImplementedError
       end
     end

data/lib/a11y/lint/rules/{image_tag_missing_alt.rb → perceivable/image_tag_missing_alt.rb}

@@ -7,16 +7,16 @@ module A11y
     module Rules
       # Checks that image_tag calls include an alt option (WCAG 1.1.1).
       class ImageTagMissingAlt < Rule
-        def check(node)
-          return unless an_image_tag_without_an_alt_attribute?(node)
+        def check
+          return unless an_image_tag_without_an_alt_attribute?
 
           "image_tag is missing an alt option (WCAG 1.1.1)"
         end
 
         private
 
-        def an_image_tag_without_an_alt_attribute?(node)
-          code = node.ruby_code
+        def an_image_tag_without_an_alt_attribute?
+          code = @node.ruby_code
           return false unless code
 
           sexp = Ripper.sexp(code)
@@ -26,6 +26,8 @@ module A11y
           call && !alt_key_within?(call)
         end
 
+        # Walks the Ripper S-expression tree to find
+        # the image_tag call node, if present.
         def extract_image_tag_call(sexp)
           return unless sexp.is_a?(Array)
           return sexp if image_tag_call?(sexp)
@@ -38,6 +40,9 @@ module A11y
           nil
         end
 
+        # Matches both calling styles:
+        #   image_tag "photo.jpg"  => :command
+        #   image_tag("photo.jpg") => :method_add_arg
         def image_tag_call?(sexp)
           case sexp
           in [:command, [:@ident, "image_tag", *], *] then true
@@ -46,6 +51,8 @@ module A11y
           end
         end
 
+        # Recursively searches the sexp for an
+        # :assoc_new node whose key is "alt".
         def alt_key_within?(sexp)
           return true if alt_key?(sexp)
           return false unless sexp.is_a?(Array)
@@ -53,12 +60,29 @@ module A11y
           sexp.any? { |child| alt_key_within?(child) }
         end
 
+        # Checks if a sexp is a hash pair (assoc_new)
+        # with "alt" as the key.
         def alt_key?(sexp)
           return false unless sexp.is_a?(Array) && sexp[0] == :assoc_new
 
-          key = sexp[1]
-          (key in [:@label, "alt:", *]) ||
-            (key in [:string_literal, [:string_content, [:@tstring_content, "alt", *]]])
+          alt_key_value?(sexp[1])
+        end
+
+        def alt_key_value?(key)
+          alt_symbol_key?(key) || alt_string_key?(key)
+        end
+
+        # Matches symbol-style key: `alt: "..."`
+        def alt_symbol_key?(key)
+          key in [:@label, "alt:", *]
+        end
+
+        # Matches string-style key: `"alt" => "..."`
+        def alt_string_key?(key)
+          key in [
+            :string_literal,
+            [:string_content, [:@tstring_content, "alt", *]]
+          ]
         end
       end
     end

data/lib/a11y/lint/rules/{img_missing_alt.rb → perceivable/img_missing_alt.rb}

@@ -5,16 +5,16 @@ module A11y
     module Rules
       # Checks that img tags include an alt attribute (WCAG 1.1.1).
       class ImgMissingAlt < Rule
-        def check(node)
-          return unless an_image_without_an_alt_attribute?(node)
+        def check
+          return unless an_image_without_an_alt_attribute?
 
           "img tag is missing an alt attribute (WCAG 1.1.1)"
         end
 
         private
 
-        def an_image_without_an_alt_attribute?(node)
-          node.tag_name == "img" && !node.attribute?("alt")
+        def an_image_without_an_alt_attribute?
+          @node.tag_name == "img" && !@node.attribute?("alt")
         end
       end
     end

data/lib/a11y/lint/rules/perceivable/list_invalid_children.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module A11y
+  module Lint
+    module Rules
+      # Checks that <ul> and <ol> only directly contain <li>, <script>,
+      # or <template> elements (WCAG 1.3.1).
+      class ListInvalidChildren < Rule
+        LIST_TAGS = %w[ul ol].freeze
+        ALLOWED_CHILDREN = %w[li script template].freeze
+
+        def check
+          return unless list_with_invalid_children?
+
+          offense_message(@node.tag_name, invalid_children.first.tag_name)
+        end
+
+        private
+
+        def list_with_invalid_children?
+          LIST_TAGS.include?(@node.tag_name) && invalid_children.any?
+        end
+
+        def invalid_children
+          @invalid_children ||= @node.children.reject do |child|
+            ALLOWED_CHILDREN.include?(child.tag_name)
+          end
+        end
+
+        def offense_message(parent, child)
+          "<#{parent}> must only directly contain <li>, <script>, " \
+            "or <template> elements, found <#{child}> (WCAG 1.3.1)"
+        end
+      end
+    end
+  end
+end

data/lib/a11y/lint/rules/{link_missing_accessible_name.rb → robust/missing_accessible_name.rb}

@@ -5,54 +5,72 @@ require "ripper"
 module A11y
   module Lint
     module Rules
-      # Checks that link_to / external_link_to calls with empty text
-      # or block content include an aria-label (WCAG 4.1.2).
-      class LinkMissingAccessibleName < Rule
-        LINK_METHODS = %w[link_to external_link_to].freeze
+      # Checks that link_to, external_link_to, and button_tag calls with
+      # empty text or block content include an aria-label (WCAG 4.1.2).
+      class MissingAccessibleName < Rule
+        METHODS = %w[link_to external_link_to button_tag].freeze
 
-        def check(node)
-          code = node.ruby_code
-          return unless code
+        def check
+          return unless (code = @node.ruby_code)
 
           clean_code = code.sub(/\s+do\s*\z/, "")
           is_block = clean_code != code
-          call = parse_link_call(clean_code)
+          call = parse_call(clean_code)
           return unless call
           return if aria_label_within?(call)
           return unless first_arg_empty_string?(call) || is_block
 
-          "link missing an accessible name requires an aria-label (WCAG 4.1.2)"
+          offense_message(extract_method_name(call))
         end
 
         private
 
-        def parse_link_call(code)
+        def offense_message(method_name)
+          <<~MSG.strip
+            #{method_name} missing an accessible name \
+            requires an aria-label (WCAG 4.1.2)
+          MSG
+        end
+
+        def parse_call(code)
           sexp = Ripper.sexp(code)
           return unless sexp
 
-          extract_link_call(sexp)
+          extract_matching_call(sexp)
         end
 
-        def extract_link_call(sexp)
+        def extract_matching_call(sexp)
           return unless sexp.is_a?(Array)
-          return sexp if link_call?(sexp)
+          return sexp if matching_call?(sexp)
 
           sexp.each do |child|
-            result = extract_link_call(child)
+            result = extract_matching_call(child)
             return result if result
           end
 
           nil
         end
 
-        def link_call?(sexp)
+        def matching_call?(sexp)
+          name = call_method_name(sexp)
+          name ? METHODS.include?(name) : false
+        end
+
+        def call_method_name(sexp)
           case sexp
-          in [:command, [:@ident, name, *], *] if LINK_METHODS.include?(name) then true
-          in [:method_add_arg, [:fcall, [:@ident, name, *]], *] if LINK_METHODS.include?(name) then true
-          else false
+          in [:command, [:@ident, name, *], *]
+            name
+          in [:method_add_arg,
+              [:fcall, [:@ident, name, *]], *]
+            name
+          else nil
           end
         end
 
+        def extract_method_name(call)
+          call_method_name(call)
+        end
+
         def first_arg_empty_string?(call)
           args = extract_args(call)
           return false unless args&.first
@@ -63,7 +81,9 @@ module A11y
         def extract_args(call)
           case call
           in [:command, _, [:args_add_block, args, *]] then args
-          in [:method_add_arg, _, [:arg_paren, [:args_add_block, args, *]]] then args
+          in [:method_add_arg, _,
+             [:arg_paren, [:args_add_block, args, *]]]
+            then args
           in [:method_add_arg, _, [:arg_paren, Array => args]] then args
           else nil
           end
@@ -94,13 +114,17 @@ module A11y
         end
 
         def label_key?(sexp)
-          sexp.is_a?(Array) && sexp[0] == :assoc_new && (sexp[1] in [:@label, "label:", *])
+          sexp.is_a?(Array) &&
+            sexp[0] == :assoc_new &&
+            (sexp[1] in [:@label, "label:", *])
         end
 
         def aria_label_string_key?(sexp)
           return false unless sexp.is_a?(Array) && sexp[0] == :assoc_new
 
-          sexp[1] in [:string_literal, [:string_content, [:@tstring_content, "aria-label", *]]]
+          sexp[1] in [:string_literal,
+            [:string_content,
+              [:@tstring_content, "aria-label", *]]]
         end
       end
     end

data/lib/a11y/lint/slim_runner.rb

@@ -27,6 +27,7 @@ module A11y
         @line += 1 if sexp[0] == :newline
         new_node = Node.new(sexp, line: @line)
         check_node(new_node) if html_tag?(sexp) || slim_output?(sexp)
+        @line += continuation_newlines(sexp)
         sexp.each { |child| walk(child) }
       end
 
@@ -38,17 +39,30 @@ module A11y
         sexp[0] == :slim && sexp[1] == :output
       end
 
+      # Counts extra source lines consumed by backslash-continued
+      # multiline expressions in :output and :control nodes.
+      # Slim collapses these into one AST node whose ruby_code
+      # string retains the original newlines.
+      def continuation_newlines(sexp)
+        code = case sexp
+               in [:slim, :output, _, String => c, *] then c
+               in [:slim, :control, String => c, *] then c
+               else return 0
+               end
+        code.count("\n")
+      end
+
       def node?(sexp)
         sexp.is_a?(Array) && !sexp.empty? && sexp[0].is_a?(Symbol)
       end
 
       def check_node(node)
-        rules.each do |rule|
-          message = rule.check(node)
+        rules.each do |rule_class|
+          message = rule_class.check(node)
           next unless message
 
           @offenses << Offense.new(
-            rule: rule.name,
+            rule: rule_class.rule_name,
             filename: @filename,
             line: node.line,
             message: message

data/lib/a11y/lint/version.rb

@@ -2,6 +2,6 @@
 
 module A11y
   module Lint
-    VERSION = "0.6.0"
+    VERSION = "0.7.1"
   end
 end

data/lib/a11y/lint.rb

@@ -6,10 +6,12 @@ require_relative "lint/version"
 require_relative "lint/offense"
 require_relative "lint/node"
 require_relative "lint/erb_node"
+require_relative "lint/configuration"
 require_relative "lint/rule"
-require_relative "lint/rules/image_tag_missing_alt"
-require_relative "lint/rules/img_missing_alt"
-require_relative "lint/rules/link_missing_accessible_name"
+require_relative "lint/rules/perceivable/image_tag_missing_alt"
+require_relative "lint/rules/perceivable/img_missing_alt"
+require_relative "lint/rules/perceivable/list_invalid_children"
+require_relative "lint/rules/robust/missing_accessible_name"
 require_relative "lint/slim_runner"
 require_relative "lint/erb_runner"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: a11y-lint
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -56,14 +56,16 @@ files:
 - exe/a11y-lint
 - lib/a11y/lint.rb
 - lib/a11y/lint/cli.rb
+- lib/a11y/lint/configuration.rb
 - lib/a11y/lint/erb_node.rb
 - lib/a11y/lint/erb_runner.rb
 - lib/a11y/lint/node.rb
 - lib/a11y/lint/offense.rb
 - lib/a11y/lint/rule.rb
-- lib/a11y/lint/rules/image_tag_missing_alt.rb
-- lib/a11y/lint/rules/img_missing_alt.rb
-- lib/a11y/lint/rules/link_missing_accessible_name.rb
+- lib/a11y/lint/rules/perceivable/image_tag_missing_alt.rb
+- lib/a11y/lint/rules/perceivable/img_missing_alt.rb
+- lib/a11y/lint/rules/perceivable/list_invalid_children.rb
+- lib/a11y/lint/rules/robust/missing_accessible_name.rb
 - lib/a11y/lint/slim_runner.rb
 - lib/a11y/lint/version.rb
 - sig/a11y/lint.rbs