a11y-lint 0.14.0 → 0.14.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c80dbcc5dec24d2850b42b84b2bbf512dc792f9c77e41ba4fd778d792c0d750a
-  data.tar.gz: aff2c4e3002a785f2f8fbfc5cfe9b115466cc3850299114b8724a82b5c71e52a
+  metadata.gz: 27003e9edd9b1055dd6c2ddd37ac6da8958bb3a608f5bb8fbfa103eb167ddb0e
+  data.tar.gz: 5af458356a27d126373c8780ca2cec362d7d2e05b70edfdb45236a90f70b82a9
 SHA512:
-  metadata.gz: c6431784a0c4704f7040953c2ef881678b13e61fee513f639c1ff4de019a4bb1599633638902764dc0cf9f9b25fe553349262639e0f30029033e5498f252f23a
-  data.tar.gz: 5b140955d0e2eadc1fefe2314bf85a16f0129d0c2cf569deb507c829ca0cf1aeb633ed601d670e4eef814d1b825a0576a5ad5d41e733bf4c8fceae7b6040f4fe
+  metadata.gz: a03ec8dba3eea02eaf7195e6b06f7ef60e628fbe4fd0de1a36c646123e5a335f8244fb10d6fe1a10f3570d95d133e9e32ccdd3ab0619401b93ccf82c6040c4d7
+  data.tar.gz: 632ec73a902867c26723f05814717ec53f8f32df73d3d9db7f99afc5cfd1530899cb418e1172b4076de7b0b2f72a48f2ce179f08c506ec7a013cf4ebcae6b625

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/task.md

@@ -0,0 +1,37 @@
+---
+description: Capture a free-form idea as a GitHub issue in the current repo
+argument-hint: <idea>
+allowed-tools: Bash(gh issue create:*), Bash(gh repo view:*), Bash(grep:*), Bash(rg:*), Bash(ls:*), Bash(find:*), Read, Glob, Grep
+---
+
+Take the free-form idea below and turn it into a well-formed GitHub issue in the current repo.
+
+Idea: $ARGUMENTS
+
+## What to do
+
+1. **Refine** the idea into:
+   - A clear **title** (≤ ~70 chars, sentence case, no trailing period)
+   - A **body** with these sections (omit any that don't apply):
+     - **Problem / idea** — restate the idea clearly in 1–3 sentences
+     - **Proposed approach** — only include if the approach is obvious from the idea
+     - **Files likely involved** — only include if you can quickly identify them from the repo (e.g. a new rule idea should point at the right WCAG principle directory under `lib/a11y/lint/rules/`)
+
+2. **Clarify only if necessary** — one round, max. Voice input drops context, but too many questions defeat frictionless capture. Skip clarification when the idea is unambiguous. Typical clarifications: bug vs. feature, which rule/file, which template pipeline (Slim/ERB/Phlex).
+
+3. **Create the issue** with `gh issue create --title "..." --body "$(cat <<'EOF' ... EOF)"` against the current repo. Do **not** pass `--repo`. Do **not** add labels.
+
+4. **Return the issue URL** that `gh issue create` prints. Keep your final reply to one line — just the URL (and a one-line summary if helpful).
+
+## Out of scope
+
+- Auto-suggesting labels
+- Cross-repo support
+- Duplicate detection / linking related issues
+- Editing or closing existing issues
+
+## Style notes
+
+- Bias toward **fast capture** over thoroughness — the issue can always be edited on GitHub.
+- Don't pad the body with boilerplate. If "Proposed approach" or "Files likely involved" isn't obvious, leave it out.
+- Match the tone of recent issues in this repo if you can quickly check one.

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- `AnchorMissingAccessibleName` and `ButtonMissingAccessibleName` no longer report Phlex `a`/`button` tags whose accessible text comes from a phlex-rails value helper (`t`, `translate`, `l`, `localize`, `pluralize`, `truncate`, the `number_to_*` / `number_with_*` helpers, `highlight`, `excerpt`) or Phlex's built-in `text`. Previously only `plain` was recognized
+
 ## [0.14.0] - 2026-04-28
 
 ### Changed

data/docs/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to the a11y-lint docs site
+
+## Authoring rule reference pages
+
+Rule pages live in `src/rules/`, one Markdown file per WCAG concept. Each rule class is an anchor section within that page.
+
+### Showing example code in multiple template languages
+
+a11y-lint supports ERB, Slim, and Phlex. When a rule page shows example code, render it through the `Shared::CodeTabs` component so all three pipelines collapse into one tabbed block instead of three stacked code blocks.
+
+ERB is required and is the default tab. Slim and Phlex are optional — omit either kwarg and the tab won't render.
+
+```erb
+<%= render Shared::CodeTabs.new(
+  erb: <<~ERB,
+    <img src="hero.jpg" alt="Team celebrating after a product launch">
+  ERB
+  slim: <<~SLIM,
+    img src="hero.jpg" alt="Team celebrating after a product launch"
+  SLIM
+  phlex: <<~PHLEX,
+    img(src: "hero.jpg", alt: "Team celebrating after a product launch")
+  PHLEX
+) %>
+```
+
+The component takes care of:
+
+- Rouge syntax highlighting per tab (using the `erb`, `slim`, and `ruby` lexers).
+- WAI-ARIA tab pattern: `role="tablist"` / `role="tab"` / `role="tabpanel"` with full `aria-*` wiring.
+- Keyboard navigation: Left/Right arrows move between tabs, Home/End jump to the first/last tab, Enter/Space activate, Tab moves into the panel.
+- A no-JavaScript fallback that shows the ERB panel only.
+- `prefers-reduced-motion`.
+
+Multiple instances on the same page get unique IDs automatically.

data/docs/src/_components/shared/code_tabs.css

@@ -0,0 +1,57 @@
+.code-tabs {
+  margin: 1.5rem 0;
+}
+
+.code-tabs__tablist {
+  display: none;
+  gap: 0.25rem;
+  border-bottom: 1px solid #ddd;
+}
+
+.code-tabs.is-enhanced .code-tabs__tablist {
+  display: flex;
+}
+
+.code-tabs__tab {
+  background: transparent;
+  border: 1px solid transparent;
+  border-bottom: none;
+  border-radius: 4px 4px 0 0;
+  padding: 0.5rem 1rem;
+  font: inherit;
+  font-weight: 600;
+  color: var(--body-color);
+  cursor: pointer;
+  margin-bottom: -1px;
+}
+
+.code-tabs__tab[aria-selected="true"] {
+  background: white;
+  border-color: #ddd;
+  color: var(--heading-color);
+}
+
+.code-tabs__tab:focus-visible,
+.code-tabs__panel:focus-visible {
+  outline: 2px solid var(--action-color);
+  outline-offset: 2px;
+}
+
+.code-tabs__panel {
+  border: 1px solid #ddd;
+  border-radius: 0 4px 4px 4px;
+}
+
+.code-tabs.is-enhanced .code-tabs__panel {
+  border-top-left-radius: 0;
+}
+
+.code-tabs__panel pre {
+  margin: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .code-tabs__tab {
+    transition: none;
+  }
+}

data/docs/src/_components/shared/code_tabs.erb

@@ -0,0 +1,30 @@
+<div class="code-tabs">
+  <div class="code-tabs__tablist" role="tablist" aria-label="Template language">
+    <% tabs.each_with_index do |tab, i| %>
+      <button
+        type="button"
+        role="tab"
+        id="<%= tab_id(tab[:key]) %>"
+        aria-controls="<%= panel_id(tab[:key]) %>"
+        aria-selected="<%= i.zero? %>"
+        tabindex="<%= i.zero? ? 0 : -1 %>"
+        class="code-tabs__tab"
+      >
+        <%= tab[:label] %>
+      </button>
+    <% end %>
+  </div>
+
+  <% tabs.each_with_index do |tab, i| %>
+    <div
+      role="tabpanel"
+      id="<%= panel_id(tab[:key]) %>"
+      aria-labelledby="<%= tab_id(tab[:key]) %>"
+      class="code-tabs__panel"
+      tabindex="0"
+      <%= "hidden" unless i.zero? %>
+    >
+      <%= raw highlighted(tab[:key], tab[:lexer]) %>
+    </div>
+  <% end %>
+</div>

data/docs/src/_components/shared/code_tabs.js

@@ -0,0 +1,54 @@
+function initCodeTabs(root) {
+  if (root.classList.contains("is-enhanced")) return
+
+  const tabs = Array.from(root.querySelectorAll('[role="tab"]'))
+  const panels = Array.from(root.querySelectorAll('[role="tabpanel"]'))
+  if (tabs.length === 0) return
+
+  root.classList.add("is-enhanced")
+
+  function activate(index, { focus = true } = {}) {
+    tabs.forEach((tab, i) => {
+      const selected = i === index
+      tab.setAttribute("aria-selected", String(selected))
+      tab.setAttribute("tabindex", selected ? "0" : "-1")
+      panels[i].hidden = !selected
+    })
+    if (focus) tabs[index].focus()
+  }
+
+  tabs.forEach((tab, i) => {
+    tab.addEventListener("click", () => activate(i))
+    tab.addEventListener("keydown", (event) => {
+      let next = null
+      switch (event.key) {
+        case "ArrowRight":
+          next = (i + 1) % tabs.length
+          break
+        case "ArrowLeft":
+          next = (i - 1 + tabs.length) % tabs.length
+          break
+        case "Home":
+          next = 0
+          break
+        case "End":
+          next = tabs.length - 1
+          break
+        default:
+          return
+      }
+      event.preventDefault()
+      activate(next)
+    })
+  })
+}
+
+function initAllCodeTabs() {
+  document.querySelectorAll(".code-tabs").forEach(initCodeTabs)
+}
+
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", initAllCodeTabs)
+} else {
+  initAllCodeTabs()
+}

data/docs/src/_components/shared/code_tabs.rb

@@ -0,0 +1,36 @@
+require "rouge"
+require "securerandom"
+
+class Shared::CodeTabs < Bridgetown::Component
+  TABS = [
+    { key: :erb,   label: "ERB",   lexer: "erb" },
+    { key: :slim,  label: "Slim",  lexer: "slim" },
+    { key: :phlex, label: "Phlex", lexer: "ruby" }
+  ].freeze
+
+  attr_reader :id
+
+  def initialize(erb:, slim: nil, phlex: nil)
+    @samples = { erb: erb, slim: slim, phlex: phlex }
+    @id = "code-tabs-#{SecureRandom.hex(4)}"
+  end
+
+  def tabs
+    TABS.select { |tab| @samples[tab[:key]] }
+  end
+
+  def tab_id(key)
+    "#{id}-tab-#{key}"
+  end
+
+  def panel_id(key)
+    "#{id}-panel-#{key}"
+  end
+
+  def highlighted(key, lexer_name)
+    formatter = Rouge::Formatters::HTML.new
+    lexer = Rouge::Lexer.find(lexer_name) || Rouge::Lexers::PlainText.new
+    inner = formatter.format(lexer.lex(@samples[key].to_s))
+    %(<pre class="highlight"><code>#{inner}</code></pre>)
+  end
+end

data/docs/src/rules/images-need-alt-text.md

@@ -67,15 +67,31 @@ Applies to: HTML `<img>` elements.
 
 ### Bad
 
-```erb
-<img src="hero.jpg">
-```
+<%= render Shared::CodeTabs.new(
+  erb: <<~ERB,
+    <img src="hero.jpg">
+  ERB
+  slim: <<~SLIM,
+    img src="hero.jpg"
+  SLIM
+  phlex: <<~PHLEX,
+    img(src: "hero.jpg")
+  PHLEX
+) %>
 
 ### Good
 
-```erb
-<img src="hero.jpg" alt="Team celebrating after a product launch">
-```
+<%= render Shared::CodeTabs.new(
+  erb: <<~ERB,
+    <img src="hero.jpg" alt="Team celebrating after a product launch">
+  ERB
+  slim: <<~SLIM,
+    img src="hero.jpg" alt="Team celebrating after a product launch"
+  SLIM
+  phlex: <<~PHLEX,
+    img(src: "hero.jpg", alt: "Team celebrating after a product launch")
+  PHLEX
+) %>
 
 For a decorative image, use an empty `alt` so assistive tech skips it:
 

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/phlex_node.rb

@@ -100,7 +100,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 +149,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,180 @@
+# 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:)
+          new(block, children).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)
+        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)
+          @block = block
+          @children = children
+        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
+          return false if PhlexNode.html_tag?(name)
+          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 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,93 @@
+# 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_children
+          block_node ? block_node.child_nodes.compact : []
+        end
+
+        def block_has_text?(children = [])
+          BlockTextScanner.scan(block_node, children: children)
+        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
@@ -30,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
@@ -58,114 +58,100 @@ 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)
         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 hidden_wrapper_tag?(call)
       end
 
-      def hidden_wrapper_tag?(call_node)
+      def hidden_wrapper_tag?(call)
         classes = configuration.hidden_wrapper_classes
         return false if classes.empty?
 
-        tag_class_values(call_node).any? { |klass| classes.include?(klass) }
-      end
-
-      def tag_class_values(call_node)
-        return [] unless call_node.arguments
-
-        PhlexNode.kwarg_class_values(call_node)
-      end
-
-      def tag_block_has_text?(block, children)
-        return false unless block.is_a?(Prism::BlockNode)
-
-        scan_for_text(block) || children.any?(&:text_content?)
+        call.class_values.any? { |klass| classes.include?(klass) }
       end
 
-      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
-      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? && hidden_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) && node.name.to_s == "plain"
+      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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: a11y-lint
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.14.2
 platform: ruby
 authors:
 - Abdullah Hashim
@@ -45,6 +45,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/commands/implement.md"
+- ".claude/commands/task.md"
 - ".claude/rules/testing.md"
 - ".rubocop.yml"
 - CHANGELOG.md
@@ -55,6 +57,7 @@ files:
 - Rakefile
 - docs/.gitignore
 - docs/.ruby-version
+- docs/CONTRIBUTING.md
 - docs/Gemfile
 - docs/Gemfile.lock
 - docs/README.md
@@ -80,6 +83,10 @@ files:
 - docs/src/404.html
 - docs/src/500.html
 - docs/src/CNAME
+- docs/src/_components/shared/code_tabs.css
+- docs/src/_components/shared/code_tabs.erb
+- docs/src/_components/shared/code_tabs.js
+- docs/src/_components/shared/code_tabs.rb
 - docs/src/_components/shared/navbar.erb
 - docs/src/_components/shared/navbar.rb
 - docs/src/_data/site_metadata.yml
@@ -111,6 +118,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