Unified special tag separators on colon and added a docs drift-guard linter.

[AlexSkrypnyk]

Summary

Unifies the library's special Behat tag separator convention so that all parametrized tags consistently use a colon between the tag name and its value (@prefix:value). AccessibilityTrait was the only parametrized tag still using a hyphen for the value separator (@accessibility-critical); this PR aligns it with the six other parametrized tags (@module:help, @breakpoint:mobile, @email:default, etc.). A new drift-guard linter in docs.php - executed as part of ahoy lint-docs and gated in CI - enforces the colon convention going forward by scanning all trait docblocks, step examples, and feature files against a canonical tag registry. 180 lines of data-provider-driven PHPUnit tests cover the four new functions at 100% line coverage.

BREAKING CHANGE

The seven threshold tags for AccessibilityTrait now use a colon separator instead of a hyphen. Consumers must rename these tags in their feature files:

Before	After
@accessibility-critical	@accessibility:critical
@accessibility-serious	@accessibility:serious
@accessibility-moderate	@accessibility:moderate
@accessibility-minor	@accessibility:minor
@accessibility-any	@accessibility:any
@accessibility-warning	@accessibility:warning
@accessibility-strict	@accessibility:strict

The bare @accessibility tag is unchanged. The hyphen forms no longer resolve and the new linter will reject them. AccessibilityTrait shipped in 3.9.0 / 3.10.0 only, so the blast radius is small.

Changes

src/AccessibilityTrait.php

• Updated trait docblock and inline comments to document @accessibility:critical / @accessibility:serious etc. instead of the old hyphen forms.
• Changed accessibilityGetThreshold() to match on : instead of - when extracting the threshold value from the scenario tag.

docs.php

• Added tag_registry(): canonical map of all 13 special library tags, each classified as parametrized (expects @prefix:value) or flag (stands alone).
• Added extract_tags(): extracts @tag tokens from arbitrary text, skipping email addresses and @@ sequences, deduplicating results.
• Added validate_tag(): checks a single tag against the registry and returns an error message when a parametrized prefix is followed by - instead of :.
• Added validate_tags(): orchestrates validation across all trait descriptions, step examples, and every .feature file under tests/behat/features/; wired into main() alongside the existing validate() call.

tests/phpunit/src/DocsTest.php

• testTagRegistry(): smoke-checks registry shape and type values.
• testValidateTag() with dataProviderValidateTag() (35 cases): valid colon forms, bare tags, flag tags with hyphens in their name, unknown tags, and every violation class.
• testExtractTags() with dataProviderExtractTags() (15 cases): empty input, email-address skipping, @@ skipping, trailing-punctuation stripping, deduplication.
• testValidateTagsFromInfo(): exercises all branching paths inside validate_tags() for in-memory trait info.
• testValidateTagsFromFeatureFiles(): writes two temporary feature files and asserts that only the dirty one produces an error.
• testValidateTagsReturnsNoErrorsForCleanInput(): confirms zero errors for fully conforming input.

tests/behat/features/accessibility.feature and STEPS.md

• Updated all @accessibility-* tag references to @accessibility:*.

Before / After

# Tag usage in feature files

Before:
  @javascript @accessibility-critical
  Scenario: Page must have no critical violations

  @javascript @accessibility-warning
  Scenario: Advisory scan, never blocks the build

After:
  @javascript @accessibility:critical
  Scenario: Page must have no critical violations

  @javascript @accessibility:warning
  Scenario: Advisory scan, never blocks the build

# New linter gate (runs in `ahoy lint-docs` / CI)

Before: no guard - a typo or copy-paste could silently re-introduce
        the hyphen form with no error.

After:  docs.php validate_tags() scans docblocks, examples, and
        feature files; any parametrized tag written as @prefix-value
        fails the build with a message such as:
          AccessibilityTrait - Tag "@accessibility-critical" must use
          ":" as the value separator (use "@accessibility:critical",
          not "@accessibility-critical").

PR Summary: Unify Behat Tag Separator Convention to Colons

Objective

Standardize the library's special Behat tag convention to use colons (:) between tag names and values, aligning parametrized threshold tags in AccessibilityTrait with existing conventions used in other tags like @module:help and @breakpoint:mobile.

Changes

Documentation Updates

• STEPS.md: Updated AccessibilityTrait documentation to rename supported @accessibility impact tags from hyphenated forms (@accessibility-critical, @accessibility-serious, etc.) to colon-suffixed forms (@accessibility:critical, @accessibility:serious, etc.). The bare @accessibility tag remains unchanged. All threshold semantics preserved.

Core Implementation Changes

• src/AccessibilityTrait.php: Updated docblock and internal documentation to use colon-based variants instead of dash-based variants. Modified accessibilityResolveTags() to recognize variant tags by requiring the auto tag prefix followed by : instead of - when extracting and applying threshold/fail-on-incomplete settings.

Test Updates

• tests/behat/features/accessibility.feature: Updated Behat scenario tags from @accessibility-warning and @accessibility-critical to their colon-based equivalents (@accessibility:warning, @accessibility:critical).

New Linter Infrastructure

• docs.php: Added four new tag validation functions:
  • tag_registry(): Canonical map of 13 special library tags classified as parametrized or flag
  • extract_tags(): Extracts @tag tokens while skipping email addresses and @@ sequences
  • validate_tag(): Checks tags against the registry for compliance with colon convention
  • validate_tags(): Orchestrates validation across trait descriptions, step examples, and .feature files
  • Updated main() to integrate tag validation errors into the linting pipeline, executing as part of ahoy lint-docs command and CI

Test Coverage

• tests/phpunit/src/DocsTest.php: Added comprehensive test coverage with 180 lines of data-provider-driven PHPUnit tests covering the four new functions at 100% line coverage, including:
  • Tag registry classification tests
  • Single-tag validation with comprehensive valid/invalid tag strings
  • Tag extraction from prose with edge cases (emails, punctuation, duplicates, backticks, parentheses, hyphenated tags)
  • Integration-style validation across structured info and feature files on disk
  • Clean input validation tests

Breaking Change

This PR introduces a breaking change affecting consumers of AccessibilityTrait. However, the blast radius is small as the trait was only shipped in versions 3.9.0 and 3.10.0.

Step Definition Compliance

All step definitions referenced in the modified feature files conform to the CONTRIBUTING.md step definition guidelines. No violations detected.

Effort Assessment

• Code Review Effort: Medium across all modified files
• Testing: Comprehensive coverage for new linter functions with 100% line coverage achieved

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 26a0f308-a37a-4a7a-947a-b28598ceb8df

📥 Commits

Reviewing files that changed from the base of the PR and between b56cb57 and b86e687.

📒 Files selected for processing (5)

• STEPS.md
• docs.php
• src/AccessibilityTrait.php
• tests/behat/features/accessibility.feature
• tests/phpunit/src/DocsTest.php

---

Walkthrough

Renames accessibility Behat tag separators from dash (@accessibility-critical) to colon (@accessibility:critical) across the trait implementation, docblocks, STEPS.md, and Behat feature tests. Adds a new tag-validation subsystem in docs.php with four functions that enforce the colon-separator convention by scanning documentation and .feature files, and covers those functions with new PHPUnit tests.

Changes

Accessibility tag syntax migration and validation enforcement

Layer / File(s)	Summary
Tag delimiter change in implementation, docs, and Behat tests src/AccessibilityTrait.php, STEPS.md, tests/behat/features/accessibility.feature	accessibilityResolveTags() switches the variant delimiter check from - to :. All docblocks in AccessibilityTrait.php and the STEPS.md tag listings are updated to reflect @accessibility:<level> syntax. Three scenario tags in the Behat feature file are renamed from @accessibility-* to @accessibility:*.
Tag validation subsystem in docs.php docs.php	Adds tag_registry(), extract_tags(), validate_tag(), and validate_tags(). validate_tags() scans trait descriptions, step examples, and tests/behat/features/*.feature files, extracts @tag tokens (skipping email addresses and @@), and reports any parametrized tags that still use - as a value separator. main() merges results into its $errors array.
PHPUnit tests for tag validation tests/phpunit/src/DocsTest.php	Adds #[CoversFunction] attributes for the four new functions plus testTagRegistry, testValidateTag (data-provider driven), testExtractTags (data-provider driven with edge cases), and three validate_tags integration tests covering info-based errors, feature-file-based errors, and clean-input no-error assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• drevops/behat-steps#643: Introduces the AccessibilityTrait functionality that this PR modifies — the same trait, tag-parsing implementation, and feature tests are directly updated here to switch from dash to colon separators.

Suggested labels

Needs review

🐇 A hyphen fell out of my ear,
A colon hopped in — how perfectly clear!
@accessibility:critical I say,
The tags now behave the correct way,
The validator checks, and I give a cheer! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.94% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main objectives: unifying tag separators to colons and adding a docs drift-guard linter.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/unify-tag-formats

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.85%. Comparing base (b56cb57) to head (b86e687).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #662      +/-   ##
==========================================
+ Coverage   96.80%   96.85%   +0.05%     
==========================================
  Files          46       46              
  Lines        3757     3817      +60     
==========================================
+ Hits         3637     3697      +60     
  Misses        120      120              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.