a11y-lint 0.14.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27003e9edd9b1055dd6c2ddd37ac6da8958bb3a608f5bb8fbfa103eb167ddb0e
-  data.tar.gz: 5af458356a27d126373c8780ca2cec362d7d2e05b70edfdb45236a90f70b82a9
+  metadata.gz: 8621f3bad2e339bfff4c19dda38dc6f9e46a1195dd832c1d41506435f7836701
+  data.tar.gz: e7522df50471a67ec8693b7f1a006190dff8d319628ed30ffd978a6540287692
 SHA512:
-  metadata.gz: a03ec8dba3eea02eaf7195e6b06f7ef60e628fbe4fd0de1a36c646123e5a335f8244fb10d6fe1a10f3570d95d133e9e32ccdd3ab0619401b93ccf82c6040c4d7
-  data.tar.gz: 632ec73a902867c26723f05814717ec53f8f32df73d3d9db7f99afc5cfd1530899cb418e1172b4076de7b0b2f72a48f2ce179f08c506ec7a013cf4ebcae6b625
+  metadata.gz: c18b6aea457244af85b7e21d749f32841c0cd45cb898eda52a0f8e271478ee0ad99da9f1f539c5c6ae97537edfe212b820b3139a6865dcc46a77396511c2d2f8
+  data.tar.gz: f9dc521203ff94d686ef5d4cb01cf0d382ff18d1be8e83807197a8de54e0dba441fbe0d23fd6301fac0523c13d582d70ab4c5763eaf002ecb9c6963e7579c78f

data/.claude/commands/prepare-release.md

@@ -0,0 +1,62 @@
+---
+description: Scaffold gem release prep — preflight, bump, smoke, then push a release branch and open a PR
+argument-hint: [patch|minor|major|X.Y.Z]
+allowed-tools: Bash(git status:*), Bash(git fetch:*), Bash(git log:*), Bash(git diff:*), Bash(git tag:*), Bash(git rev-parse:*), Bash(git rev-list:*), Bash(git branch:*), Bash(git checkout:*), Bash(git switch:*), Bash(git restore:*), Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(gh pr create:*), Bash(gh pr view:*), Bash(bundle install:*), Bash(bundle exec:*), Bash(grep:*), Bash(rg:*), Bash(ls:*), Bash(date:*), Read, Edit, Write, Glob, Grep
+---
+
+Prepare a gem release. Bump kind: **$ARGUMENTS** (empty = infer from commits since last tag).
+
+End state: a `release-X.Y.Z` branch pushed to origin with an open PR titled `Release X.Y.Z` and body `🎉`. The PR diff is the review surface — the CHANGELOG is the release notes.
+
+The user runs the irreversible steps after the PR merges. **Never** run `bundle exec rake release`, `gem push pkg/a11y-lint-X.Y.Z.gem`, or `git tag vX.Y.Z && git push origin vX.Y.Z`.
+
+## Preflight
+
+Bail loudly on any failure — don't try to fix state silently.
+
+- On `main`, working tree clean, not behind `origin/main` (`git fetch origin main` then `git rev-list --count HEAD..origin/main` → `0`).
+- `lib/a11y/lint/version.rb` `VERSION`, `Gemfile.lock`'s `a11y-lint (X.Y.Z)` line under `PATH → specs:`, and the latest `git tag --sort=-v:refname | head -1` (stripped of leading `v`) all agree. A mismatch usually means a prior release was half-finished — surface it and stop.
+
+## Bump
+
+If `$ARGUMENTS` is empty, infer from `git log <latest_tag>..HEAD`:
+
+- Any commit subject containing `Breaking`, or starting with `Add ` or `Change ` → **minor**
+- Otherwise → **patch**
+
+This gem is pre-1.0; breaking changes still bump the minor (no major path). Print the inferred bump and the resulting `X.Y.Z`, then proceed without confirming.
+
+If `$ARGUMENTS` is `patch`/`minor`/`major`, bump that segment. If it's `X.Y.Z`, use literally. Anything else → bail.
+
+## Apply
+
+1. Edit `lib/a11y/lint/version.rb` — replace the `VERSION = "..."` literal.
+2. Edit `CHANGELOG.md` — insert `## [X.Y.Z] - YYYY-MM-DD` (today, absolute via `date +%Y-%m-%d`) directly below `## [Unreleased]` with blank lines around it. The Unreleased entries shift down to attribute the new release; the new Unreleased block stays empty.
+3. `bundle install` — should change only `Gemfile.lock`'s `a11y-lint (X.Y.Z)` line. Surface anything else.
+
+## Verify
+
+- `bundle exec rake` — tests + RuboCop. Bail on red.
+- `bundle exec a11y-lint test/fixtures/dummy_app` — capture offense count. Then run the same command against the prior release's fixtures with the *current* linter to isolate any linter regression on stable input:
+  ```
+  git checkout <latest_tag> -- test/fixtures/dummy_app
+  bundle exec a11y-lint test/fixtures/dummy_app
+  git checkout HEAD -- test/fixtures/dummy_app
+  ```
+  Report `prev → current`. A non-trivial change is a linter regression — surface it.
+
+## Shape check
+
+`git diff --stat` should touch only `lib/a11y/lint/version.rb`, `CHANGELOG.md`, `Gemfile.lock`. Anything else is a red flag — stop and ask before pushing.
+
+## Branch + PR
+
+```
+git checkout -b release-X.Y.Z
+git add lib/a11y/lint/version.rb CHANGELOG.md Gemfile.lock
+git commit -m "Release X.Y.Z"
+git push -u origin release-X.Y.Z
+gh pr create --title "Release X.Y.Z" --body "🎉"
+```
+
+Print the PR URL.

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-05-06
+
+### Changed
+
+- **Breaking:** `.a11y-lint.yml`'s `hidden_wrapper_classes` key is now `inaccessible_wrapper_classes`. Behavior is unchanged. The rename brings the key into line with the new `accessible_wrapper_classes` (below). Projects with `hidden_wrapper_classes` in their config need to rename it
+
+### Added
+
+- `.a11y-lint.yml` now supports a top-level `accessible_wrapper_classes` list. Inside Phlex `a`/`button` tags whose direct child has a matching class, `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` treat ambiguous bare calls — receiverless calls whose name matches an HTML tag, with no arguments and no block — as text-emitting method calls rather than empty HTML elements. Fixes false positives on the `span(class: "sr-only") { label }` pattern, where `label` is an instance method that parses as a `Prism::CallNode` indistinguishable from the `<label>` HTML tag. Opt-in; default is no special handling. Distinct from `inaccessible_wrapper_classes` (which excludes the wrapper from the parent's accessible name); a wrapper-class list member here stays in the parent's children with `text_content?` set to true. No-op in the Slim and ERB pipelines, which have no analogous ambiguity
+
 ## [0.14.2] - 2026-05-05
 
 ### Fixed

data/lib/a11y/lint/configuration.rb

@@ -42,9 +42,14 @@ 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
+      def inaccessible_wrapper_classes
+        @inaccessible_wrapper_classes ||=
+          Array(@config["inaccessible_wrapper_classes"]).map(&:to_s).freeze
+      end
+
+      def accessible_wrapper_classes
+        @accessible_wrapper_classes ||=
+          Array(@config["accessible_wrapper_classes"]).map(&:to_s).freeze
       end
 
       def enabled_rules

data/lib/a11y/lint/erb_element_node.rb

@@ -47,7 +47,7 @@ module A11y
       end
 
       def text_content?
-        return false if hidden_wrapper?(@nokogiri_node)
+        return false if inaccessible_wrapper?(@nokogiri_node)
 
         visible_text_or_output?(@nokogiri_node)
       end
@@ -58,7 +58,7 @@ module A11y
       # to the accessible name.
       def children
         @nokogiri_node.element_children.filter_map do |child|
-          next if hidden_wrapper?(child)
+          next if inaccessible_wrapper?(child)
 
           ErbElementNode.new(
             nokogiri_node: child, line: child.line,
@@ -70,7 +70,7 @@ module A11y
       private
 
       def visible_text_or_output?(node)
-        return false if hidden_wrapper?(node)
+        return false if inaccessible_wrapper?(node)
         return true if own_text_or_marker?(node)
 
         node.element_children.any? { |c| visible_text_or_output?(c) }
@@ -86,8 +86,8 @@ module A11y
         end
       end
 
-      def hidden_wrapper?(node)
-        classes = configuration.hidden_wrapper_classes
+      def inaccessible_wrapper?(node)
+        classes = configuration.inaccessible_wrapper_classes
         return false if classes.empty?
 
         node_classes(node).any? { |klass| classes.include?(klass) }

data/lib/a11y/lint/erb_runner.rb

@@ -98,7 +98,7 @@ module A11y
         indexed_codes = []
         html = indexed_marker_html(block_content, indexed_codes)
         fragment = Nokogiri::HTML4::DocumentFragment.parse(html)
-        strip_hidden_wrappers!(fragment)
+        strip_inaccessible_wrappers!(fragment)
 
         remaining = fragment.to_html
         visible_codes = indexed_codes.each_with_index.filter_map do |code, i|
@@ -118,23 +118,23 @@ module A11y
         !html.gsub(/#{ERB_OUTPUT_MARKER}\d+_/, "").strip.empty?
       end
 
-      def strip_hidden_wrappers!(node)
-        return if configuration.hidden_wrapper_classes.empty?
+      def strip_inaccessible_wrappers!(node)
+        return if configuration.inaccessible_wrapper_classes.empty?
 
         node.element_children.each do |child|
-          if hidden_wrapper_element?(child)
+          if inaccessible_wrapper_element?(child)
             child.remove
           else
-            strip_hidden_wrappers!(child)
+            strip_inaccessible_wrappers!(child)
           end
         end
       end
 
-      def hidden_wrapper_element?(node)
+      def inaccessible_wrapper_element?(node)
         value = node.attributes["class"]&.value
         return false unless value.is_a?(String)
 
-        classes = configuration.hidden_wrapper_classes
+        classes = configuration.inaccessible_wrapper_classes
         value.split.any? { |klass| classes.include?(klass) }
       end
 

data/lib/a11y/lint/phlex_node.rb

@@ -85,6 +85,13 @@ module A11y
         )
       end
 
+      # Resolves a Phlex tag call's `class:` kwarg to a list of class names.
+      # Intentionally narrow: only matches a literal `Prism::StringNode`.
+      # Misses array form (`class: ["sr-only", other]`), interpolation
+      # (`class: "sr-only #{foo}"`), helper-wrapped (`class: cn("sr-only")`),
+      # and computed values (`class: some_method`). Wrapper-class config
+      # (`inaccessible_wrapper_classes`, `accessible_wrapper_classes`)
+      # therefore only matches authors who write a single static literal.
       def self.kwarg_class_values(call_node)
         return [] unless call_node.arguments
 

data/lib/a11y/lint/phlex_runner/block_text_scanner.rb

@@ -22,15 +22,15 @@ module A11y
           highlight excerpt
         ].to_set.freeze
 
-        def self.scan(block, children:)
-          new(block, children).scan
+        def self.scan(block, children:, accessible_wrapper: false)
+          new(block, children:, accessible_wrapper:).scan
         end
 
         # Public recognizer for a single Prism node — used by PhlexRunner
         # to inspect a tag's first positional argument, where Phlex emits
         # the value as text content (`a("Click", href: "/x")`).
         def self.text_emitting?(node)
-          new(nil, []).text_emitting?(node)
+          new(nil, children: []).text_emitting?(node)
         end
 
         def self.non_blank_string_literal?(node)
@@ -50,9 +50,10 @@ module A11y
           end
         end
 
-        def initialize(block, children)
+        def initialize(block, children:, accessible_wrapper: false)
           @block = block
           @children = children
+          @accessible_wrapper = accessible_wrapper
         end
 
         def scan
@@ -119,7 +120,9 @@ module A11y
           return true if call.receiver
 
           name = call.name.to_s
-          return false if PhlexNode.html_tag?(name)
+          if PhlexNode.html_tag?(name)
+            return accessible_wrapper? && bare_call?(call)
+          end
           return true if TEXT_CALLS.include?(name)
 
           # Lowercase receiverless calls (locals, helper methods) auto-emit
@@ -128,6 +131,14 @@ module A11y
           lowercase_name?(name)
         end
 
+        def bare_call?(call)
+          call.arguments.nil? && call.block.nil?
+        end
+
+        def accessible_wrapper?
+          @accessible_wrapper
+        end
+
         def conditional_container?(node)
           node.is_a?(Prism::IfNode) ||
             node.is_a?(Prism::UnlessNode) ||

data/lib/a11y/lint/phlex_runner/phlex_call.rb

@@ -57,12 +57,8 @@ module A11y
           block.is_a?(Prism::BlockArgumentNode)
         end
 
-        def block_children
-          block_node ? block_node.child_nodes.compact : []
-        end
-
-        def block_has_text?(children = [])
-          BlockTextScanner.scan(block_node, children: children)
+        def block_has_text?(children = [], accessible_wrapper: false)
+          BlockTextScanner.scan(block_node, children:, accessible_wrapper:)
         end
 
         # Phlex's tag API emits the first positional argument as text

data/lib/a11y/lint/phlex_runner.rb

@@ -91,17 +91,30 @@ module A11y
 
       def gather_tag_child(call, result)
         kids = collect_block_children(call.block_node)
-        has_text = call.arg_has_text? || call.block_has_text?(kids)
+        has_text = call.arg_has_text? ||
+                   call.block_has_text?(
+                     kids,
+                     accessible_wrapper: accessible_wrapper_tag?(call)
+                   )
         tag = PhlexNode.build_tag(
           call.call_node, children: kids, text_content: has_text,
                           configuration: configuration
         )
         check_node(tag)
-        result << tag unless hidden_wrapper_tag?(call)
+        result << tag unless inaccessible_wrapper_tag?(call)
       end
 
-      def hidden_wrapper_tag?(call)
-        classes = configuration.hidden_wrapper_classes
+      def inaccessible_wrapper_tag?(call)
+        wrapper_class_match?(call, configuration.inaccessible_wrapper_classes)
+      end
+
+      def accessible_wrapper_tag?(call)
+        wrapper_class_match?(
+          call, configuration.accessible_wrapper_classes
+        )
+      end
+
+      def wrapper_class_match?(call, classes)
         return false if classes.empty?
 
         call.class_values.any? { |klass| classes.include?(klass) }
@@ -131,7 +144,7 @@ module A11y
       end
 
       def handle_call_block_child(child_call, codes)
-        return false if child_call.tag? && hidden_wrapper_tag?(child_call)
+        return false if child_call.tag? && inaccessible_wrapper_tag?(child_call)
         return true if tag_call_has_text_block?(child_call)
         return false if child_call.tag?
 

data/lib/a11y/lint/slim_node.rb

@@ -91,7 +91,7 @@ module A11y
 
       def collect_output_codes(sexp)
         return [] unless sexp.is_a?(Array)
-        return [] if hidden_wrapper_sexp?(sexp)
+        return [] if inaccessible_wrapper_sexp?(sexp)
         return [sexp[3]] if slim_output_sexp?(sexp)
 
         sexp.flat_map { |child| collect_output_codes(child) }
@@ -103,7 +103,7 @@ module A11y
 
       def block_text_content?(sexp)
         return false unless sexp.is_a?(Array)
-        return false if hidden_wrapper_sexp?(sexp)
+        return false if inaccessible_wrapper_sexp?(sexp)
         return true if slim_text_sexp?(sexp) || html_tag_sexp?(sexp)
 
         sexp.any? { |child| block_text_content?(child) }
@@ -111,18 +111,18 @@ module A11y
 
       def text_or_output?(sexp)
         return false unless sexp.is_a?(Array)
-        return false if hidden_wrapper_sexp?(sexp)
+        return false if inaccessible_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)
+      def inaccessible_wrapper_sexp?(sexp)
         return false unless html_tag_sexp?(sexp)
-        return false if configuration.hidden_wrapper_classes.empty?
+        return false if configuration.inaccessible_wrapper_classes.empty?
 
         class_values(sexp[3]).any? do |klass|
-          configuration.hidden_wrapper_classes.include?(klass)
+          configuration.inaccessible_wrapper_classes.include?(klass)
         end
       end
 

data/lib/a11y/lint/version.rb

@@ -2,6 +2,6 @@
 
 module A11y
   module Lint
-    VERSION = "0.14.2"
+    VERSION = "0.15.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: a11y-lint
 version: !ruby/object:Gem::Version
-  version: 0.14.2
+  version: 0.15.0
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -46,6 +46,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".claude/commands/implement.md"
+- ".claude/commands/prepare-release.md"
 - ".claude/commands/task.md"
 - ".claude/rules/testing.md"
 - ".rubocop.yml"