axe-cuprite 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8cd30e650ead2d72475783c40ed7cc6d7d251527913d2b28ae6643402d9d032b
+  data.tar.gz: a5624b4d65f5859b7fd4a710f79a5bf6fb85b6c9f409e2bc50de393f8563ad86
+SHA512:
+  metadata.gz: 89f99c88d792b73c748f25c4b7a33d0b136a5a939e77f14b6fcbc437f88ab5eb85e4ebf0f182843ce23ea1a04857e619104db06aaf476eb065c9252aebe2c22b
+  data.tar.gz: 274b40778c354c1ee42a04958fdda2b1f9513f9220d94b300495a62cf86c86d862655d504c1366ead311e65ba1410104f3eec9fc51f280faee098464113d8af9

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-06
+
+### Added
+- Initial release of **axe-cuprite**.
+- Vendored **axe-core 4.12.0** (`lib/axe/cuprite/vendor/axe.min.js`, MPL-2.0).
+- `AxeCuprite::Runner` — framework-agnostic runner that injects axe and runs it
+  through Capybara's driver-neutral JavaScript API (works on Cuprite/Ferrum with
+  **zero Selenium dependency**), with a configurable timeout decoupled from
+  `Capybara.default_max_wait_time`.
+- Typed result objects: `Results`, `Violation`, `Node`, `ContrastData`.
+- RSpec matcher `be_axe_clean` (alias `be_accessible`) with chainable DSL:
+  `.within`, `.excluding`, `.checking_only`, `.skipping`, `.according_to`,
+  `.with_options`, `.with_timeout`. Actionable, grouped failure messages that
+  surface fg/bg color and contrast ratio for color-contrast violations.
+- `AxeCuprite.configure` for timeout, default options/tags, global skip-list,
+  auto-inject toggle, and report-only mode.
+- `rake axe:update[VERSION]` to refresh the vendored axe-core engine and bump
+  the `AXE_CORE_VERSION` constant.

data/LICENSE.txt

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Abdullah Hashim / Guided Rails
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---------------------------------------------------------------------------
+
+This gem vendors the axe-core JavaScript engine
+(lib/axe/cuprite/vendor/axe.min.js), which is licensed separately under the
+Mozilla Public License, version 2.0 (MPL-2.0). axe-core is Copyright (c)
+Deque Systems, Inc. The full MPL-2.0 text is included alongside the vendored
+file at lib/axe/cuprite/vendor/axe-core-LICENSE.txt. The MIT license above
+applies only to the axe-cuprite gem's own source code.

data/README.md

@@ -0,0 +1,257 @@
+# axe-cuprite
+
+Run the [axe-core](https://github.com/dequelabs/axe-core) accessibility engine
+against pages in your **Capybara system/feature tests driven by
+[Cuprite](https://github.com/rubycdp/cuprite)** (the CDP/Ferrum headless-Chrome
+driver) — and assert on the results with readable RSpec matchers.
+
+The headline use case is **catching WCAG color-contrast regressions in CI**, but
+you can run any axe rule.
+
+```ruby
+expect(page).to be_axe_clean.checking_only(:color_contrast)
+```
+
+## Why this gem exists
+
+Deque's official `axe-core-capybara` / `axe-core-rspec` gems **do not work with
+Cuprite**. To inject and run axe they reach for the underlying **Selenium**
+`browser` object inside the Capybara driver. Cuprite has no Selenium browser, so
+they break.
+
+**axe-cuprite never touches Selenium-specific driver internals.** axe-core is
+just a JavaScript file — a driver-agnostic engine — so we drive it exclusively
+through Capybara's **driver-neutral** JavaScript API (`execute_script`,
+`evaluate_async_script`), which Cuprite fully implements. That single decision is
+what makes this gem work where the official one doesn't. As a bonus it stays
+driver-agnostic (it works on any real-browser Capybara driver), but **Cuprite is
+the primary, must-pass target.**
+
+There is no runtime dependency on Selenium, Cuprite, or Ferrum — the only runtime
+dependency is Capybara. You bring your own driver.
+
+## Installation
+
+```ruby
+# Gemfile
+group :test do
+  gem "axe-cuprite"
+end
+```
+
+```sh
+bundle install
+```
+
+Then load the RSpec matchers from your `spec/spec_helper.rb` (or `rails_helper.rb`):
+
+```ruby
+require "axe/cuprite/rspec"
+```
+
+That mixes `be_axe_clean` / `be_accessible` into your example groups. If you only
+want the framework-agnostic runner (no RSpec), `require "axe/cuprite"` instead.
+
+## Usage
+
+### The matcher
+
+```ruby
+RSpec.describe "Dashboard", type: :system do
+  it "has no accessibility violations" do
+    visit dashboard_path
+    expect(page).to be_axe_clean
+  end
+
+  it "passes WCAG AA color contrast" do
+    visit dashboard_path
+    expect(page).to be_axe_clean.checking_only(:color_contrast)
+  end
+end
+```
+
+`be_accessible` is an alias for `be_axe_clean` — use whichever reads better.
+
+### Chainable DSL
+
+All chainers return the matcher, so they compose in any order:
+
+| Method | What it does | axe concept |
+| --- | --- | --- |
+| `.within(*selectors)` | Only test inside these elements | context `include` |
+| `.excluding(*selectors)` | Skip these elements | context `exclude` |
+| `.checking_only(*rules)` | Run only these rules | `runOnly` type `rule` |
+| `.according_to(*tags)` | Run only rules with these tags | `runOnly` type `tag` |
+| `.skipping(*rules)` | Disable these rules | `rules: { id: { enabled: false } }` |
+| `.with_options(hash)` | Merge raw axe run options (escape hatch) | — |
+| `.with_timeout(seconds)` | Override the axe timeout for this assertion | — |
+
+Rule ids and tags accept **either** friendly Ruby symbols **or** axe's own ids —
+underscores and hyphens are normalized for you, so `:color_contrast` and
+`"color-contrast"` are equivalent, as are `:best_practice` and `"best-practice"`.
+
+```ruby
+expect(page).to be_axe_clean
+  .within("#main")
+  .excluding(".third-party-widget")
+  .according_to(:wcag2a, :wcag2aa)
+  .skipping(:region)
+```
+
+> Note: `.checking_only` (specific rules) and `.according_to` (tags) are mutually
+> exclusive — axe's `runOnly` accepts one or the other. Combining them raises an
+> `ArgumentError`.
+
+### Actionable failure messages
+
+Failures are grouped by rule, with impact, help URL, the offending selector, and
+an HTML snippet. For **color-contrast** violations they surface exactly what you
+need to fix it:
+
+```
+expected page to be axe-clean, but found 1 violation across 1 element:
+
+  ● [serious] color-contrast — Elements must meet minimum color contrast ratio thresholds (1 element)
+    https://dequeuniversity.com/rules/axe/4.12/color-contrast
+      - #faded
+        <p id="faded" style="color:#585858; opacity:0.5; background:#ffffff;"> This text token passes…
+        contrast 2.34:1 (needs 4.5:1) — fg #acacac on bg #ffffff, font 12pt/normal
+```
+
+### The runner (no RSpec required)
+
+```ruby
+results = AxeCuprite::Runner.new(page).run(
+  context: "#main",
+  options: { runOnly: { type: "rule", values: ["color-contrast"] } }
+)
+
+results.passes?               # => false
+results.violations            # => [AxeCuprite::Violation, ...]
+v = results.violations.first
+v.id                          # => "color-contrast"
+v.impact                      # => "serious"
+node = v.nodes.first
+node.selector                 # => "#faded"
+cd = node.contrast_data       # => AxeCuprite::ContrastData (nil for non-contrast rules)
+cd.contrast_ratio             # => 2.34
+cd.expected_contrast_ratio    # => 4.5
+cd.fg_color                   # => "#acacac"
+cd.bg_color                   # => "#ffffff"
+```
+
+`context` maps to axe's context arg (a CSS selector string, or a hash with
+`:include` / `:exclude`). `options` maps to axe's run options and is deep-merged
+on top of your configured defaults. Only `violations` and `incomplete` are
+carried back across the CDP boundary — the full results object (with
+`passes`/`inapplicable`) can be huge.
+
+## Configuration
+
+```ruby
+AxeCuprite.configure do |c|
+  c.timeout         = 30          # seconds to wait for axe.run (see caveats)
+  c.default_options = {}          # axe run options merged into every run
+  c.default_tags    = %w[wcag2a wcag2aa]  # applied when no rule/tag scope is given
+  c.skip_rules      = [:region]   # globally disabled rules
+  c.auto_inject     = true        # (re)inject axe on demand inside #run
+  c.report_only     = false       # log violations instead of failing (see below)
+  c.logger          = Logger.new($stdout)
+end
+```
+
+### Report-only mode
+
+Set `report_only = true` to **log** violations instead of failing the example.
+This eases incremental adoption on an existing app — you can see what axe finds
+without turning the suite red. Negated assertions (`expect(page).not_to
+be_axe_clean`) ignore this flag.
+
+## Caveats & engineering notes
+
+### Timeout (decoupled from `default_max_wait_time`)
+
+This is the subtle one. Ferrum's async evaluation wraps your promise in a
+`setTimeout(reject, wait * 1000)` and **rejects with "timed out promise"** if it
+doesn't resolve in time. Through Capybara's `evaluate_async_script`, that `wait`
+is `Capybara.default_max_wait_time` — often 2 seconds, which `axe.run` on a real
+page routinely exceeds.
+
+axe-cuprite avoids this trap: on Cuprite it calls Ferrum's
+`page.evaluate_async(script, explicit_wait, *args)` **directly**, with its own
+timeout (default **30s**, configurable) that is completely **decoupled from
+`default_max_wait_time`**. On non-Ferrum drivers it falls back to
+`evaluate_async_script` under a temporarily-raised wait time. If axe still
+doesn't finish, you get a clear `AxeCuprite::TimeoutError` telling you to raise
+the timeout or scope the run with `.within`.
+
+Tune it globally (`c.timeout = 60`) or per assertion (`.with_timeout(60)`).
+
+### Content-Security-Policy
+
+axe-cuprite's primary injection path is `execute_script`, which on Cuprite runs
+via CDP `Runtime.evaluate` and is **not subject to the page's CSP** — so a strict
+`script-src` policy generally doesn't block it (there's a test proving this). If
+injection ever fails to land axe, the gem falls back to Ferrum's
+`add_script_tag(content:)` and raises `AxeCuprite::InjectionError` with a
+CSP-pointed message if even that fails.
+
+### Idempotent injection
+
+axe (~500KB) is injected once per page and guarded on
+`typeof window.axe === 'undefined'`, so repeated assertions on the same page don't
+re-inject. After a full navigation axe is gone; the runner detects the
+"axe not defined" case and re-injects on demand. You can force a re-inject with
+`AxeCuprite::Runner.new(page).inject!(force: true)`.
+
+### Page readiness & iframes
+
+axe runs against the DOM as it is the moment you assert — there are no implicit
+sleeps. Assert on a fully loaded/settled page (after Turbo frames, etc.). axe
+traverses **same-origin** iframes by default; cross-origin frames are inaccessible
+to the engine.
+
+## Updating the vendored axe-core engine
+
+axe-core is **vendored** into the gem (`lib/axe/cuprite/vendor/axe.min.js`) — it
+is never fetched at runtime. The current version is recorded in
+`AxeCuprite::AXE_CORE_VERSION` and printed in the banner of the vendored file.
+
+To refresh it:
+
+```sh
+rake 'axe:update[4.12.0]'   # pin a version
+rake axe:update             # or grab the latest from npm
+rake axe:version            # print the currently vendored version
+```
+
+`axe:update` downloads `axe.min.js` and its `LICENSE` from unpkg and bumps the
+`AXE_CORE_VERSION` constant. Note the bump in `CHANGELOG.md`.
+
+## Licensing
+
+- **axe-cuprite's own code** is licensed under the **MIT** license — see
+  [`LICENSE.txt`](LICENSE.txt).
+- The **vendored axe-core engine** (`lib/axe/cuprite/vendor/axe.min.js`) is a
+  separate work by Deque Systems, licensed under the **Mozilla Public License,
+  version 2.0 (MPL-2.0)**. Its full license text ships alongside it at
+  [`lib/axe/cuprite/vendor/axe-core-LICENSE.txt`](lib/axe/cuprite/vendor/axe-core-LICENSE.txt).
+
+The two licenses are kept distinct and apply to their respective files.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec   # runs the suite under Cuprite (requires Chrome/Chromium)
+```
+
+The gem's own test suite uses Capybara + Cuprite against a tiny static fixture
+app, including a known-bad `opacity`-induced contrast page, to prove the
+no-Selenium path end to end.
+
+## Out of scope
+
+- Static template/CSS analysis (this is render-time only, by design).
+- Selenium/Watir support (the official `axe-core-*` gems already cover those).
+- Auto-fixing violations.

data/lib/axe/cuprite/configuration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module AxeCuprite
+  # Global configuration for axe-cuprite. Accessed via AxeCuprite.configure.
+  class Configuration
+    # Maximum time (seconds) to wait for axe.run to resolve. This is decoupled
+    # from Capybara.default_max_wait_time — see Injector. Default 30s because
+    # axe.run on a large page routinely exceeds Capybara's 2s default.
+    attr_accessor :timeout
+
+    # Default axe run options merged into every run (e.g. { resultTypes: [...] }).
+    # Caller / matcher options are deep-merged on top of these.
+    attr_accessor :default_options
+
+    # Default axe tags applied when no explicit rule/tag scoping is given,
+    # e.g. ["wcag2a", "wcag2aa"]. Empty means "run all default rules".
+    attr_accessor :default_tags
+
+    # Global list of rule ids (or symbols) to disable on every run, e.g.
+    # [:color_contrast, "region"]. Normalized underscores -> hyphens.
+    attr_accessor :skip_rules
+
+    # When true, axe is (re)injected on every #run if missing. Injection is
+    # always idempotent (guarded on `typeof window.axe`), so this mainly
+    # controls whether a stale axe (after navigation) is re-injected.
+    attr_accessor :auto_inject
+
+    # When true, the matcher logs violations instead of failing the example.
+    # Eases incremental adoption on an existing app.
+    attr_accessor :report_only
+
+    # Logger used for report_only output and warnings.
+    attr_accessor :logger
+
+    def initialize
+      @timeout         = 30
+      @default_options = {}
+      @default_tags    = []
+      @skip_rules      = []
+      @auto_inject     = true
+      @report_only     = false
+      @logger          = default_logger
+    end
+
+    private
+
+    def default_logger
+      Logger.new($stdout).tap do |log|
+        log.progname = "axe-cuprite"
+        log.formatter = proc { |severity, _time, progname, msg| "[#{progname}] #{severity}: #{msg}\n" }
+      end
+    end
+  end
+end

data/lib/axe/cuprite/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AxeCuprite
+  # Base class for all axe-cuprite errors.
+  class Error < StandardError; end
+
+  # Raised when axe.run does not resolve within the configured timeout.
+  # Usually means the page is very large or axe is stuck — bump the timeout
+  # via AxeCuprite.configure { |c| c.timeout = ... } or the matcher/runner.
+  class TimeoutError < Error; end
+
+  # Raised when axe-core itself reports an error while running (e.g. an
+  # invalid context selector or run option).
+  class AxeRunError < Error; end
+
+  # Raised when axe could not be injected into the page (e.g. a strict
+  # Content-Security-Policy blocked both inline injection and add_script_tag).
+  class InjectionError < Error; end
+end

data/lib/axe/cuprite/injector.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module AxeCuprite
+  # Handles getting axe-core onto the page and running it — entirely through
+  # Capybara's driver-neutral JS API, with a Ferrum fast-path for Cuprite.
+  #
+  # This is the make-or-break class. Two things are easy to get wrong:
+  #
+  #   1. The async-callback convention. Ferrum's `evaluate_async` (and Capybara's
+  #      `evaluate_async_script`, which Cuprite delegates to it) wraps your
+  #      expression in a Promise and appends the resolve callback as the LAST
+  #      entry of `arguments`. So we resolve via `arguments[arguments.length - 1]`.
+  #
+  #   2. The timeout. Ferrum wraps the promise in a `setTimeout(reject, wait*1000)`.
+  #      Through `evaluate_async_script` that `wait` is Capybara.default_max_wait_time
+  #      (often 2s) — far too short for `axe.run` on a real page. So on Cuprite we
+  #      call Ferrum's `page.evaluate_async(expr, explicit_wait, *args)` DIRECTLY
+  #      with our own timeout, decoupled from default_max_wait_time entirely.
+  class Injector
+    # JS run inside Ferrum's promise wrapper. `arguments[0]` is the axe context,
+    # `arguments[1]` the run options, and the LAST argument is the resolve
+    # callback Ferrum appended. We slim the result down to a JSON-safe payload —
+    # never returning the full results object (passes/inapplicable can be huge).
+    RUN_JS = <<~JS
+      var ctx = arguments[0];
+      var opts = arguments[1] || {};
+      var done = arguments[arguments.length - 1];
+      if (typeof window.axe === 'undefined' || typeof window.axe.run !== 'function') {
+        done({ error: 'axe-core is not present on the page' });
+        return;
+      }
+      var promise = ctx ? window.axe.run(ctx, opts) : window.axe.run(opts);
+      promise.then(function (results) {
+        done({
+          violations: results.violations,
+          incomplete: results.incomplete,
+          url: results.url,
+          timestamp: results.timestamp,
+          testEngine: results.testEngine
+        });
+      }).catch(function (err) {
+        done({ error: (err && err.message) ? err.message : String(err) });
+      });
+    JS
+
+    # JS expression that reports whether axe is loaded and runnable.
+    PRESENCE_JS = "typeof window.axe !== 'undefined' && typeof window.axe.run === 'function'"
+
+    def initialize(page, configuration = AxeCuprite.configuration)
+      @page = page
+      @config = configuration
+    end
+
+    # Is axe-core present and runnable on the current page?
+    def injected?
+      @page.evaluate_script(PRESENCE_JS) == true
+    end
+
+    # Ensure axe is present. Idempotent: does nothing if already injected
+    # (so repeated assertions on one page don't re-send ~500KB), unless force:.
+    # Returns true if it actually injected, false if it was already there.
+    def ensure_injected!(force: false)
+      return false if !force && injected?
+
+      inject_source!
+      true
+    end
+
+    # Inject the vendored axe-core source into the page. Primary path is
+    # Capybara's driver-neutral execute_script (which, on Cuprite, runs via
+    # CDP Runtime.evaluate and is not subject to the page's CSP). If that path
+    # fails to land axe — e.g. a strict Content-Security-Policy — we fall back
+    # to Ferrum's add_script_tag.
+    def inject_source!
+      source = AxeCuprite.axe_source
+
+      begin
+        @page.execute_script(source)
+      rescue StandardError => e
+        raise InjectionError, "Failed to inject axe-core: #{e.message}" unless try_add_script_tag(source)
+      end
+
+      return true if injected?
+
+      # execute_script silently no-op'd (CSP, sandbox, ...). Try the tag fallback.
+      if try_add_script_tag(source) && injected?
+        true
+      else
+        raise InjectionError,
+              "axe-core did not load after injection. A strict Content-Security-Policy " \
+              "may be blocking script injection on the page under test."
+      end
+    end
+
+    # Run axe and return a Results object. Injects on demand if needed.
+    def run(context:, options:, timeout: nil)
+      timeout ||= @config.timeout
+      ensure_present!
+
+      raw = evaluate_axe(context, options, timeout)
+      if raw.is_a?(Hash) && raw["error"]
+        raise AxeRunError, "axe.run failed: #{raw["error"]}"
+      end
+
+      Results.new(raw)
+    end
+
+    private
+
+    # Guarantee axe is on the page before running. Honors the auto_inject toggle:
+    # when disabled, the caller is responsible for injecting first.
+    def ensure_present!
+      if @config.auto_inject
+        ensure_injected!(force: false)
+      elsif !injected?
+        raise InjectionError,
+              "axe-core is not present and auto_inject is disabled. Call Runner#inject! " \
+              "(or AxeCuprite.configure { |c| c.auto_inject = true })."
+      end
+    end
+
+    # Run axe asynchronously with an explicit timeout decoupled from
+    # Capybara.default_max_wait_time. Uses Ferrum's evaluate_async directly when
+    # available (Cuprite), else falls back to Capybara's evaluate_async_script
+    # under a temporarily-bumped wait time for other drivers.
+    def evaluate_axe(context, options, timeout)
+      fpage = ferrum_page
+      if fpage
+        fpage.evaluate_async(RUN_JS, timeout, context, options)
+      else
+        Capybara.using_wait_time(timeout) do
+          @page.evaluate_async_script(RUN_JS, context, options)
+        end
+      end
+    rescue StandardError => e
+      if timeout_error?(e)
+        raise TimeoutError,
+              "axe.run did not finish within #{timeout}s. Increase the timeout " \
+              "(AxeCuprite.configure { |c| c.timeout = N } or the matcher/runner timeout:), " \
+              "or scope the run with .within(selector). Underlying: #{e.message}"
+      end
+      raise
+    end
+
+    # The underlying Ferrum::Page, if this Capybara session is driven by Cuprite
+    # (or any Ferrum-based driver). nil for non-Ferrum drivers.
+    def ferrum_page
+      driver = @page.driver
+      return nil unless driver.respond_to?(:browser)
+
+      browser = driver.browser
+      return nil unless browser.respond_to?(:page)
+
+      fpage = browser.page
+      return nil unless fpage.respond_to?(:evaluate_async)
+
+      fpage
+    rescue StandardError
+      nil
+    end
+
+    # Best-effort CSP fallback via Ferrum's add_script_tag(content:).
+    def try_add_script_tag(source)
+      fpage = ferrum_page
+      return false unless fpage.respond_to?(:add_script_tag)
+
+      fpage.add_script_tag(content: source)
+      true
+    rescue StandardError
+      false
+    end
+
+    def timeout_error?(error)
+      return true if error.message.to_s =~ /tim(e|ed)\s*out/i
+
+      # Ferrum raises its own timeout/JS errors; match by class name without a
+      # hard dependency on the Ferrum constants (ferrum is only a dev dep here).
+      error.class.name.to_s =~ /Ferrum::(Timeout|JavaScript)Error/ &&
+        error.message.to_s =~ /timed out promise/i
+    end
+  end
+end

data/lib/axe/cuprite/normalize.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AxeCuprite
+  # Normalizes rule ids and tags so callers can use friendly Ruby symbols
+  # (:color_contrast) interchangeably with axe's own ids ("color-contrast").
+  module Normalize
+    module_function
+
+    # :color_contrast / "color_contrast" / "color-contrast" -> "color-contrast"
+    def rule(id)
+      id.to_s.strip.tr("_", "-")
+    end
+
+    # :wcag2aa -> "wcag2aa"; :best_practice -> "best-practice"
+    def tag(value)
+      value.to_s.strip.tr("_", "-")
+    end
+
+    def rules(list)
+      Array(list).map { |r| rule(r) }
+    end
+
+    def tags(list)
+      Array(list).map { |t| tag(t) }
+    end
+  end
+end