a11y-lint 0.14.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17ce590d5fc702bdcf3feb01606767c2aaa0938ca6a40b3f456737d7e9f519f2
-  data.tar.gz: b1ec19b360ccbc592fd42a9848cfdb351b924f3752b3041afa063f64bfd3e380
+  metadata.gz: 8621f3bad2e339bfff4c19dda38dc6f9e46a1195dd832c1d41506435f7836701
+  data.tar.gz: e7522df50471a67ec8693b7f1a006190dff8d319628ed30ffd978a6540287692
 SHA512:
-  metadata.gz: fa1db2cd985c446515c75808512e3663859af93d254949e51fb3638e0ee1fe7cf2172a55686f66b937476e8739a9f24910b8662ef03e285445dfab9079983be3
-  data.tar.gz: 045c3ec7a7e4442a47517020aa2cf3da15496a3e304a1768e8e067d7767f2cd0693db025711f25c05e02736c6d3f0095378e9dfb68ed1a3b19ebcb3e8232a49e
+  metadata.gz: c18b6aea457244af85b7e21d749f32841c0cd45cb898eda52a0f8e271478ee0ad99da9f1f539c5c6ae97537edfe212b820b3139a6865dcc46a77396511c2d2f8
+  data.tar.gz: f9dc521203ff94d686ef5d4cb01cf0d382ff18d1be8e83807197a8de54e0dba441fbe0d23fd6301fac0523c13d582d70ab4c5763eaf002ecb9c6963e7579c78f

data/.claude/commands/implement.md

@@ -0,0 +1,46 @@
+---
+description: Plan and implement a GitHub issue end-to-end on a new branch
+argument-hint: <issue-number>
+allowed-tools: Bash(gh issue view:*), Bash(gh repo view:*), Bash(git checkout:*), Bash(git switch:*), Bash(git branch:*), Bash(git status:*), Bash(git diff:*), Bash(bundle exec:*), Bash(bin/setup:*), Bash(bin/console:*), Bash(grep:*), Bash(rg:*), Bash(ls:*), Bash(find:*), Read, Edit, Write, Glob, Grep
+---
+
+Plan and implement GitHub issue **#$ARGUMENTS** in this repo, end-to-end, on a fresh branch. Do **not** commit or push — leave the working tree dirty for the user to review.
+
+## What to do
+
+1. **Fetch the issue.** Run `gh issue view $ARGUMENTS` (and `gh issue view $ARGUMENTS --comments` if there are comments) to read the title, body, and any discussion. Do **not** pass `--repo`.
+
+2. **Create a branch.** From the current branch, run `git checkout -b <slug>` where `<slug>` is `issue-$ARGUMENTS-<short-kebab-summary>` (e.g. `issue-87-anchor-button-phlex-helpers`). Keep it under ~50 chars. If the branch already exists, switch to it instead.
+
+3. **Plan before coding.** Produce a short plan covering:
+   - Which files you'll touch or create
+   - For new rules: the WCAG principle directory under `lib/a11y/lint/rules/`, the rule class name (see CLAUDE.md "Rule Scoping Convention"), and whether it has an HTML/helper pair
+   - Tests to add (Slim + ERB + Phlex parity per `.claude/rules/testing.md`)
+   - Dummy app fixtures to add in `test/fixtures/dummy_app/app/views/home/home.html.{slim,erb}` and any Phlex view
+   - Open questions, if any — ask once, then proceed
+
+4. **Implement the plan.**
+   - Follow `CLAUDE.md` (rule scoping, node interface, configuration loading) and `.claude/rules/testing.md` (no `setup`, all three calling styles for `ruby_code` rules, Slim/ERB/Phlex parity, inline HEREDOC fixtures).
+   - For new rules: register the rule, add good/bad examples to dummy app fixtures, and add a docs page under `docs/src/rules/` if the issue is adding a user-visible rule.
+   - Add an entry under `[Unreleased]` in `CHANGELOG.md` for any user-visible change (bug fixes, new rules, behavior changes). Skip for internal refactors and test-only changes.
+
+5. **Run the suite until green.** `bundle exec rake` runs tests + RuboCop. Iterate on failures. If a fix is non-obvious, surface it before grinding.
+
+6. **Stop without committing.** Leave changes staged-or-unstaged in the working tree. In your final reply:
+   - List the branch name
+   - Summarize what changed (files added/modified, tests added)
+   - Confirm `bundle exec rake` is green (or call out what's still failing and why)
+   - Suggest the next command (`git add -A && git commit -m "..."` or a `gh pr create` once the user is ready) — but do **not** run it
+
+## Out of scope
+
+- Committing, pushing, or opening a PR
+- Cross-repo support
+- Auto-closing the issue
+- Picking the issue automatically (always passed explicitly)
+
+## Style notes
+
+- Plan first, code second. A 5-line plan beats a 50-line one.
+- Match the conventions of recent rules and recent commits — skim `git log --oneline -20` and a nearby rule file before inventing a new pattern.
+- If the issue is ambiguous, ask **one** round of clarifying questions before implementing — voice input drops context, but too many questions defeat the point.

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/.rubocop.yml

@@ -29,5 +29,4 @@ Metrics/AbcSize:
     - "test/**/*"
 
 Metrics/MethodLength:
-  Exclude:
-    - "test/**/*"
+  Enabled: false

data/CHANGELOG.md

@@ -7,6 +7,25 @@ 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
+
+- `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` no longer report Phlex `a`/`button` tags that use the nested-hash shorthand for `aria-label` (e.g. `aria: { label: "..." }`). `PhlexNode` now flattens nested kwarg hashes the way Phlex does at render time (`aria: { label: "x" }` → `aria-label="x"`, `data: { controller: "y" }` → `data-controller="y"`), so every Phlex tag rule benefits
+- `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` no longer report Phlex `a`/`button` tags whose accessible name comes from the block's auto-emitted return value. Phlex renders the block's last expression when it's a string-like value, and `PhlexRunner` now recognizes string literals (`{ "Clear all" }`, `{ "Hi #{name}" }`), method calls with a receiver (`{ account.email }`, `{ tab[:text] }`), lowercase receiverless calls (`{ external_url }`, `{ add_label }`), method-parameter / local-variable reads, and ternary / `if` / `unless` expressions whose branches resolve to text. Capitalized component calls (`{ Pencil(...) }`) and blank string literals are still treated as having no accessible name
+- `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` no longer report Phlex `a`/`button` tags that forward a block argument (`a(href:, &block)`, `button(type: "submit", &block)`) inside a wrapper method. The accessible name is supplied by the caller's block, which can't be resolved from the tag call site, so forwarded blocks are now trusted by default
+- `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` no longer report Phlex `a`/`button` tags whose accessible name is passed as a positional argument (`a("Click me", href: "/x")`, `button("Submit", type: :submit)`). Phlex's tag API renders the first positional argument as text content, and `PhlexRunner` now applies the same recognizer used for block content to the positional arg — string literals, interpolated strings, method calls (with or without a receiver), `t`/`translate` and other phlex-rails value helpers, and local variable / method-parameter reads. Empty/whitespace strings and capitalized component calls (`a(Pencil(...), href: ...)`) are still reported
+
 ## [0.14.1] - 2026-05-03
 
 ### Fixed

data/lib/a11y/lint/cli.rb

@@ -34,7 +34,7 @@ module A11y
         option_parser.parse!(@argv)
       end
 
-      def option_parser # rubocop:disable Metrics/MethodLength
+      def option_parser
         OptionParser.new do |opts|
           opts.banner = "Usage: a11y-lint [options] [file_or_directory ...]"
 

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
 
@@ -100,7 +107,31 @@ module A11y
 
         kwarg_nodes(call_node).each_with_object({}) do |elem, h|
           key = kwarg_key(elem.key)
-          h[key] = kwarg_value(elem.value) if key
+          next unless key
+
+          if elem.value.is_a?(Prism::HashNode)
+            flatten_nested_hash(key, elem.value, h)
+          else
+            h[key] = kwarg_value(elem.value)
+          end
+        end
+      end
+
+      # Mirrors Phlex's render-time flattening of nested kwarg hashes
+      # (e.g. `aria: { label: "x" }` -> `aria-label="x"`). Inner key
+      # underscores become dashes the same way Phlex/Rails do.
+      def self.flatten_nested_hash(prefix, hash_node, attrs)
+        hash_node.elements.each do |inner|
+          next unless inner.is_a?(Prism::AssocNode)
+          next unless (inner_key = kwarg_key(inner.key))
+
+          full_key = "#{prefix}-#{inner_key.tr("_", "-")}"
+
+          if inner.value.is_a?(Prism::HashNode)
+            flatten_nested_hash(full_key, inner.value, attrs)
+          else
+            attrs[full_key] = kwarg_value(inner.value)
+          end
         end
       end
 
@@ -125,8 +156,13 @@ module A11y
         end
       end
 
-      private_class_method :kwarg_key, :kwarg_nodes, :kwarg_value,
-                           :extract_attributes
+      private_class_method(
+        :extract_attributes,
+        :flatten_nested_hash,
+        :kwarg_key,
+        :kwarg_nodes,
+        :kwarg_value
+      )
     end
   end
 end

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module A11y
+  module Lint
+    class PhlexRunner
+      # Decides whether a Phlex tag block produces accessible text.
+      # Stateless: only reads the given Prism block node and pre-collected
+      # child tags.
+      class BlockTextScanner
+        # Phlex auto-emits the return value of these calls into the document:
+        # `plain` / `text` are built-in; the rest are registered as value
+        # helpers by phlex-rails via `register_value_helper`.
+        TEXT_CALLS = %w[
+          plain text
+          t translate l localize
+          pluralize truncate
+          number_to_currency number_to_human number_to_human_size
+          number_to_percentage number_to_phone
+          number_with_delimiter number_with_precision
+          highlight excerpt
+        ].to_set.freeze
+
+        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, children: []).text_emitting?(node)
+        end
+
+        def self.non_blank_string_literal?(node)
+          case node
+          when Prism::StringNode
+            !node.unescaped.strip.empty?
+          when Prism::InterpolatedStringNode
+            node.parts.any? do |part|
+              if part.is_a?(Prism::StringNode)
+                !part.unescaped.strip.empty?
+              else
+                true
+              end
+            end
+          else
+            false
+          end
+        end
+
+        def initialize(block, children:, accessible_wrapper: false)
+          @block = block
+          @children = children
+          @accessible_wrapper = accessible_wrapper
+        end
+
+        def scan
+          return false unless @block.is_a?(Prism::BlockNode)
+
+          scan_for_text(@block) || @children.any?(&:text_content?)
+        end
+
+        def text_emitting?(node)
+          auto_emitted_text?(node)
+        end
+
+        private
+
+        # A Phlex tag block produces accessible text if any statement
+        # contains an explicit text marker (yield, plain/text/t/..., a
+        # non-blank string literal), or if the block's last expression
+        # auto-emits a value Phlex renders as text.
+        def scan_for_text(block)
+          statements = block_statements(block)
+          return false if statements.empty?
+
+          return true if statements.any? { |stmt| explicit_text?(stmt) }
+
+          auto_emitted_text?(statements.last)
+        end
+
+        def block_statements(block)
+          return [] unless block.is_a?(Prism::BlockNode)
+
+          body = block.body
+          body.is_a?(Prism::StatementsNode) ? body.body : []
+        end
+
+        def explicit_text?(node)
+          return false if node.nil?
+          return true if node.is_a?(Prism::YieldNode)
+          return true if self.class.non_blank_string_literal?(node)
+          return text_call?(node) if node.is_a?(Prism::CallNode)
+
+          # Recurse only into conditional/grouping nodes — descending into
+          # call args would treat string literals like `foo("bar")`'s "bar"
+          # as block text, which it isn't.
+          return false unless conditional_container?(node)
+
+          node.child_nodes.compact.any? { |c| explicit_text?(c) }
+        end
+
+        def auto_emitted_text?(node)
+          return false if node.nil?
+          return true if explicit_text?(node)
+
+          case node
+          when Prism::LocalVariableReadNode
+            true
+          when Prism::CallNode
+            auto_emitted_call?(node)
+          when Prism::IfNode, Prism::UnlessNode
+            if_branch_lasts(node).any? { |last| auto_emitted_text?(last) }
+          end
+        end
+
+        def auto_emitted_call?(call)
+          return true if call.receiver
+
+          name = call.name.to_s
+          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
+          # their return value. Capitalized names are Phlex components,
+          # which emit their own HTML, not text.
+          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) ||
+            node.is_a?(Prism::BeginNode) ||
+            node.is_a?(Prism::StatementsNode) ||
+            node.is_a?(Prism::ElseNode) ||
+            node.is_a?(Prism::ParenthesesNode)
+        end
+
+        def lowercase_name?(name)
+          first = name[0]
+          first && first == first.downcase && first != first.upcase
+        end
+
+        def if_branch_lasts(node)
+          if_branch_statements(node).flat_map do |stmts|
+            stmts.is_a?(Prism::StatementsNode) ? [stmts.body.last].compact : []
+          end
+        end
+
+        def if_branch_statements(node)
+          branches = [node.statements]
+          collect_else_branches(if_else_clause(node), branches)
+          branches.compact
+        end
+
+        def collect_else_branches(current, branches)
+          while current.is_a?(Prism::IfNode) || current.is_a?(Prism::UnlessNode)
+            branches << current.statements
+            current = if_else_clause(current)
+          end
+          branches << current.statements if current.is_a?(Prism::ElseNode)
+        end
+
+        def if_else_clause(node)
+          case node
+          when Prism::IfNode then node.subsequent
+          when Prism::UnlessNode then node.else_clause
+          end
+        end
+
+        def text_call?(node)
+          node.is_a?(Prism::CallNode) &&
+            node.receiver.nil? &&
+            TEXT_CALLS.include?(node.name.to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module A11y
+  module Lint
+    class PhlexRunner
+      # Wraps a `Prism::CallNode` with the predicates and block accessors
+      # PhlexRunner uses to classify and traverse Phlex view code:
+      # tag vs helper, block form (`do...end`, `&block`, none),
+      # first positional arg, class values.
+      class PhlexCall
+        # Phlex tag/helper calls are always receiverless; a call like
+        # `helpers.image_tag(...)` has a receiver and is skipped.
+        def self.wrap(node)
+          return unless node.is_a?(Prism::CallNode) && node.receiver.nil?
+
+          new(node)
+        end
+
+        def initialize(call_node)
+          @call_node = call_node
+        end
+
+        attr_reader(:call_node)
+
+        def name
+          call_node.name.to_s
+        end
+
+        def line
+          call_node.location.start_line
+        end
+
+        def tag?
+          PhlexNode.html_tag?(name)
+        end
+
+        def helper?
+          !tag?
+        end
+
+        def block
+          call_node.block
+        end
+
+        # The block as a Prism::BlockNode, or nil for `&block` forwards
+        # and calls without a block.
+        def block_node
+          block.is_a?(Prism::BlockNode) ? block : nil
+        end
+
+        # `tag(&block)` defers content to the caller; we can't see what
+        # they emit, so trust the wrapper rather than report a false
+        # positive.
+        def forwarded_block?
+          block.is_a?(Prism::BlockArgumentNode)
+        end
+
+        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
+        # content (`a("Click me", href: "/x")` is equivalent to
+        # `a(href: "/x") { "Click me" }`).
+        def arg_has_text?
+          arg = first_positional_arg
+          return false if arg.nil?
+
+          BlockTextScanner.text_emitting?(arg)
+        end
+
+        def first_positional_arg
+          return nil unless call_node.arguments
+
+          call_node.arguments.arguments.find do |arg|
+            !arg.is_a?(Prism::KeywordHashNode) &&
+              !arg.is_a?(Prism::BlockArgumentNode)
+          end
+        end
+
+        def class_values
+          PhlexNode.kwarg_class_values(call_node)
+        end
+      end
+    end
+  end
+end

data/lib/a11y/lint/phlex_runner.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "phlex_runner/block_text_scanner"
+require_relative "phlex_runner/phlex_call"
 
 module A11y
   module Lint
@@ -9,19 +11,6 @@ module A11y
     class PhlexRunner
       PHLEX_PATTERN = /\bdef\s+view_template\b/
 
-      # Phlex auto-emits the return value of these calls into the document:
-      # `plain` / `text` are built-in; the rest are registered as value
-      # helpers by phlex-rails via `register_value_helper`.
-      TEXT_CALLS = %w[
-        plain text
-        t translate l localize
-        pluralize truncate
-        number_to_currency number_to_human number_to_human_size
-        number_to_percentage number_to_phone
-        number_with_delimiter number_with_precision
-        highlight excerpt
-      ].to_set.freeze
-
       def initialize(rules = nil, configuration: Configuration.new)
         @rules = rules || configuration.enabled_rules
         @configuration = configuration
@@ -43,27 +32,25 @@ module A11y
       attr_reader :rules, :configuration
 
       def walk(node)
-        if receiverless_call?(node)
-          process_call(node)
+        if (call = PhlexCall.wrap(node))
+          process_call(call)
         else
           node.child_nodes.compact.each { |c| walk(c) }
         end
       end
 
-      def process_call(node)
-        if PhlexNode.html_tag?(node.name.to_s)
-          check_tag(node)
-        else
-          check_helper(node)
-        end
+      def process_call(call)
+        call.tag? ? check_tag(call) : check_helper(call)
       end
 
-      def check_tag(node)
-        children = collect_block_children(node.block)
-        has_text = tag_block_has_text?(node.block, children)
+      def check_tag(call)
+        children = collect_block_children(call.block_node)
+        has_text = call.forwarded_block? ||
+                   call.arg_has_text? ||
+                   call.block_has_text?(children)
         check_node(
           PhlexNode.build_tag(
-            node,
+            call.call_node,
             children: children,
             text_content: has_text,
             configuration: configuration
@@ -71,114 +58,113 @@ module A11y
         )
       end
 
-      def check_helper(node)
-        codes, has_text = analyze_helper_block(node)
+      def check_helper(call)
+        codes, has_text = analyze_helper_block(call)
         helper = PhlexNode.build_helper(
-          node,
+          call.call_node,
           block_body_codes: codes,
           block_has_text_children: has_text,
           configuration: configuration
         )
         check_node(helper)
-        walk_block(node.block)
+        walk_block(call.block_node)
       end
 
-      def collect_block_children(block)
-        return [] unless block.is_a?(Prism::BlockNode)
+      def collect_block_children(block_node)
+        return [] unless block_node
 
-        [].tap { |c| gather_children(block, c) }
+        [].tap { |c| gather_children(block_node, c) }
       end
 
       def gather_children(parent, result)
         parent.child_nodes.compact.each do |child|
-          if tag_call?(child)
-            gather_tag_child(child, result)
-          elsif receiverless_call?(child)
-            check_helper(child)
+          child_call = PhlexCall.wrap(child)
+          if child_call&.tag?
+            gather_tag_child(child_call, result)
+          elsif child_call
+            check_helper(child_call)
           else
             gather_children(child, result)
           end
         end
       end
 
-      def gather_tag_child(child, result)
-        kids = collect_block_children(child.block)
-        has_text = tag_block_has_text?(child.block, kids)
+      def gather_tag_child(call, result)
+        kids = collect_block_children(call.block_node)
+        has_text = call.arg_has_text? ||
+                   call.block_has_text?(
+                     kids,
+                     accessible_wrapper: accessible_wrapper_tag?(call)
+                   )
         tag = PhlexNode.build_tag(
-          child, children: kids, text_content: has_text,
-                 configuration: configuration
+          call.call_node, children: kids, text_content: has_text,
+                          configuration: configuration
         )
         check_node(tag)
-        result << tag unless hidden_wrapper_tag?(child)
+        result << tag unless inaccessible_wrapper_tag?(call)
       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) }
+      def inaccessible_wrapper_tag?(call)
+        wrapper_class_match?(call, configuration.inaccessible_wrapper_classes)
       end
 
-      def tag_class_values(call_node)
-        return [] unless call_node.arguments
-
-        PhlexNode.kwarg_class_values(call_node)
+      def accessible_wrapper_tag?(call)
+        wrapper_class_match?(
+          call, configuration.accessible_wrapper_classes
+        )
       end
 
-      def tag_block_has_text?(block, children)
-        return false unless block.is_a?(Prism::BlockNode)
-
-        scan_for_text(block) || children.any?(&:text_content?)
-      end
+      def wrapper_class_match?(call, classes)
+        return false if classes.empty?
 
-      def scan_for_text(node)
-        node.child_nodes.compact.any? do |child|
-          text_call?(child) || child.is_a?(Prism::YieldNode) ||
-            (!receiverless_call?(child) && scan_for_text(child))
-        end
+        call.class_values.any? { |klass| classes.include?(klass) }
       end
 
-      def analyze_helper_block(call_node)
-        block = call_node.block
-        return [nil, false] unless block.is_a?(Prism::BlockNode)
+      def analyze_helper_block(call)
+        block = call.block_node
+        return [nil, false] unless block
 
         codes = []
         has_text = scan_block_content(block, codes)
         [codes.empty? ? nil : codes, has_text]
       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)
-          next codes << child.slice if receiverless_call?(child)
-          return true if scan_block_content(child, codes)
+          return true if visit_helper_block_child(child, codes)
         end
         false
       end
-      # rubocop:enable Metrics/CyclomaticComplexity
-      # rubocop:enable Metrics/PerceivedComplexity
 
-      def walk_block(block)
-        return unless block.is_a?(Prism::BlockNode)
+      def visit_helper_block_child(child, codes)
+        child_call = PhlexCall.wrap(child)
+        return handle_call_block_child(child_call, codes) if child_call
+
+        block_child_text?(child) || scan_block_content(child, codes)
+      end
+
+      def handle_call_block_child(child_call, codes)
+        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?
 
-        block.child_nodes.compact.each { |c| walk(c) }
+        codes << child_call.call_node.slice
+        false
       end
 
-      def tag_call?(node)
-        receiverless_call?(node) && PhlexNode.html_tag?(node.name.to_s)
+      def block_child_text?(child)
+        child.is_a?(Prism::YieldNode) ||
+          BlockTextScanner.non_blank_string_literal?(child)
       end
 
-      def text_call?(node)
-        receiverless_call?(node) && TEXT_CALLS.include?(node.name.to_s)
+      def tag_call_has_text_block?(child_call)
+        child_call.tag? && !child_call.block.nil?
       end
 
-      def receiverless_call?(node)
-        node.is_a?(Prism::CallNode) && node.receiver.nil?
+      def walk_block(block_node)
+        return unless block_node
+
+        block_node.child_nodes.compact.each { |c| walk(c) }
       end
 
       def check_node(node)

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.1"
+    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.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -45,6 +45,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/commands/implement.md"
+- ".claude/commands/prepare-release.md"
 - ".claude/commands/task.md"
 - ".claude/rules/testing.md"
 - ".rubocop.yml"
@@ -117,6 +119,8 @@ files:
 - lib/a11y/lint/offense.rb
 - lib/a11y/lint/phlex_node.rb
 - lib/a11y/lint/phlex_runner.rb
+- lib/a11y/lint/phlex_runner/block_text_scanner.rb
+- lib/a11y/lint/phlex_runner/phlex_call.rb
 - lib/a11y/lint/phlex_tags.rb
 - lib/a11y/lint/ruby_code.rb
 - lib/a11y/lint/rules/perceivable/area_missing_alt.rb