rails_accessibility_testing 1.4.3 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4df6f6fa98287499a91edd38be1b081a97c3ec3ce09fade45192afe3aad7e27
-  data.tar.gz: 412a2a707455699628ab59d64c0ed3f7607c143fbdbfb7d0d70dae80bad84c8c
+  metadata.gz: ed1c4100059b21f4a777e9691fec08fe59fc59f7accecc5b8f47e15b68b913ed
+  data.tar.gz: b65e45644fd839d960ef461b5a3c350903c93ad0a89337f5f3423e2d87b7c57a
 SHA512:
-  metadata.gz: c6b0639e08a27ee874ff9fb98123f36cf429a6fcd98615beb6a17682da9a24adeb027305af4713a05cee02640d4f3d0b375245a4b55fdc03020a277a4c608f92
-  data.tar.gz: df40a9a2df569f6e49a41bc3d90812c897a827a981bc555c25dec824422aac25676b53689b323d29eaa7b6a3fa046e903cb2e510148cbaf0b4bc6797deed2c91
+  metadata.gz: 827873b27a3a9ee68c39090838d3d422a628567df1134ea4ed807be28b909e5fe3b976fb232493633ed8f521ebf2c94eca8ce051b78b844a86424095ffcc31fc
+  data.tar.gz: 2f682ff20a50b1a0ec99911f0d260a6fc6400df9aac19451538efe882a7c7dd98582895e8dd151ad4bd1d80ec998a7c86ac6906b22da46beef048f2a7226490c

data/ARCHITECTURE.md

@@ -2,20 +2,12 @@
 
 ## Project Identity
 
-### Gem Name Options
-
-After careful consideration, we've selected:
+### Gem Name
 
 **Final Name: `rails_accessibility_testing`**
 
 **Note:** The gem uses `rails_a11y` as a short alias for the generator command and CLI tool, but the official gem name is `rails_accessibility_testing`.
 
-**Alternative names considered:**
-1. `rails_accessibility_testing` - **SELECTED** - Clear and descriptive
-2. `rails_a11y` - Short alias used for CLI and generator
-3. `a11y_rails` - Alternative short form
-4. `accessible_rails` - Descriptive but longer
-
 ### Tagline
 
 **"The RSpec + RuboCop of accessibility for Rails. Catch WCAG violations before they reach production."**
@@ -34,16 +26,29 @@ Rails Accessibility Testing fills a critical gap in the Rails testing ecosystem.
 2. **Accessibility at Core**: WCAG 2.1 AA compliance is the foundation
 3. **Rails Native**: Feels like a natural part of Rails, not a bolt-on
 4. **Progressive Enhancement**: Works with zero config, scales with configuration
+5. **Performance Conscious**: Smart caching and change detection for fast feedback
 
 ### Component Architecture
 
 ```
-rails_a11y/
+rails_accessibility_testing/
 ├── Core Engine
 │   ├── Rule Engine          # Evaluates accessibility rules
-│   ├── Check Definitions    # WCAG-aligned check implementations
+│   ├── Check Definitions    # WCAG-aligned check implementations (11+ checks)
 │   └── Violation Collector  # Aggregates and formats violations
 │
+├── View Detection System (NEW in 1.5.0)
+│   ├── View File Detector   # Finds view files from routes/actions
+│   ├── Partial Detection    # Scans view files for rendered partials
+│   ├── Route Recognition    # Maps URLs to controller/action pairs
+│   └── Fuzzy Matching       # Handles action/view name mismatches
+│
+├── Performance System (NEW in 1.5.0)
+│   ├── Page Scanning Cache  # Prevents duplicate scans
+│   ├── Change Detector      # Detects file changes and impact
+│   ├── First-Run Logic      # Optimizes initial vs subsequent runs
+│   └── Asset Change Detection # Tracks CSS/JS changes
+│
 ├── Rails Integration
 │   ├── Railtie             # Rails initialization hooks
 │   ├── RSpec Integration    # RSpec helpers and matchers
@@ -76,13 +81,20 @@ Test Execution
     ↓
 System Test Helper (RSpec/Minitest)
     ↓
+Page Scanning Cache Check (NEW in 1.5.0)
+    ↓ (if not cached)
 Rule Engine
     ↓
 Check Definitions (11+ checks)
     ↓
+View File Detection (NEW in 1.5.0)
+    ├── Route Recognition
+    ├── View File Matching
+    └── Partial Detection
+    ↓
 Violation Collector
     ↓
-Error Message Builder
+Error Message Builder (with file paths)
     ↓
 Test Failure / CLI Report
 ```
@@ -91,21 +103,87 @@ Test Failure / CLI Report
 
 The rule engine is the heart of the gem. It:
 
-1. **Loads Configuration**: Reads `config/accessibility.yml` with profile support**
+1. **Loads Configuration**: Reads `config/accessibility.yml` with profile support
 2. **Applies Rule Overrides**: Respects ignored rules with comments
 3. **Executes Checks**: Runs enabled checks in order
 4. **Collects Violations**: Aggregates all violations before reporting
-5. **Formats Output**: Creates actionable error messages
+5. **Formats Output**: Creates actionable error messages with precise file locations
 
 ### Check Definition Structure
 
 Each check is a self-contained class that:
 
-- Implements a standard interface
+- Implements a standard interface (`BaseCheck`)
 - Returns violations with context
 - Includes WCAG references
 - Provides remediation suggestions
 - Can be enabled/disabled via config
+- **NEW in 1.5.0**: Includes partial detection methods for better file location
+
+### View Detection System (NEW in 1.5.0)
+
+The view detection system is a major enhancement that makes error messages much more actionable:
+
+#### View File Detection
+
+1. **Route Recognition**: Uses `Rails.application.routes.recognize_path` to get controller/action
+2. **Exact Matching**: First tries exact match (`controller/action.html.erb`)
+3. **Fuzzy Matching**: If no exact match, scans controller directory for files containing action name
+4. **Preference Logic**: Prefers files starting with action name (e.g., `search_result.html.erb` for `search` action)
+5. **Fallback**: If controller has only one view file, uses that
+
+#### Partial Detection
+
+1. **Pattern Scanning**: Scans view file content for `render` statements using multiple regex patterns
+2. **Normalization**: Handles various render syntaxes (`render 'partial'`, `render partial: 'partial'`, ERB syntax)
+3. **Path Resolution**: Resolves partial paths (handles namespaced partials like `layouts/navbar`)
+4. **Multi-Location Search**: Searches in controller directory, `shared/`, and `layouts/`
+5. **Element Mapping**: When an accessibility issue is found, determines if it's in a partial
+
+#### Module Structure
+
+```ruby
+module AccessibilityHelper
+  module PartialDetection
+    # Reusable partial detection methods
+    def find_partials_in_view_file(view_file)
+      # Scans view file for render statements
+    end
+    
+    def find_partial_for_element_in_list(controller, element_context, partial_list)
+      # Maps element to specific partial
+    end
+  end
+end
+```
+
+### Performance System (NEW in 1.5.0)
+
+#### Page Scanning Cache
+
+- **Purpose**: Prevents duplicate accessibility scans of the same page
+- **Implementation**: Module-level `@scanned_pages` hash
+- **Key Strategy**: Uses page path (preferred) or URL as cache key
+- **Lifecycle**: Persists for duration of test suite execution
+- **API**: `reset_scanned_pages_cache` for manual reset
+
+#### Change Detection
+
+- **Purpose**: Only test pages when relevant files have changed
+- **Monitored Files**: Views, controllers, helpers, CSS, JavaScript
+- **Impact Analysis**: 
+  - Main layouts → affects all pages
+  - Specific partials → affects only pages that render them
+  - Controllers → affects all routes for that controller
+  - Helpers → affects all pages (can be used anywhere)
+  - Assets → affects all pages (global impact)
+
+#### First-Run Logic
+
+- **Marker File**: `.rails_a11y_initialized` tracks first run
+- **Initial Run**: Tests all pages to establish baseline
+- **Subsequent Runs**: Only tests changed files
+- **Force Option**: `TEST_ALL_PAGES=true` environment variable
 
 ---
 
@@ -135,15 +213,34 @@ Each check is a self-contained class that:
 - More efficient than stopping at first error
 - Better for CI/CD reports
 
-### 4. View File Detection
+### 4. View File Detection (Enhanced in 1.5.0)
 
 **Why detect view files?**
 - Points developers to exact file to fix
 - Works with partials and layouts
 - Reduces debugging time
 - Makes errors actionable
+- **NEW**: Handles action/view name mismatches
+- **NEW**: Detects partials automatically
+
+### 5. Page Scanning Cache (NEW in 1.5.0)
+
+**Why cache scanned pages?**
+- Prevents duplicate work
+- Faster test execution
+- Better developer experience
+- Reduces unnecessary browser automation
+
+### 6. Smart Change Detection (Enhanced in 1.5.0)
 
-### 5. Dual Test Framework Support
+**Why detect changes?**
+- Only test what changed (faster feedback)
+- Reduces test execution time
+- Better CI/CD performance
+- **NEW**: Detects asset changes (CSS/JS)
+- **NEW**: Smart partial impact analysis
+
+### 7. Dual Test Framework Support
 
 **Why both RSpec and Minitest?**
 - Rails teams use both
@@ -157,67 +254,72 @@ Each check is a self-contained class that:
 
 ```
 lib/
-├── rails_a11y.rb                    # Main entry point
-├── rails_a11y/
+├── rails_accessibility_testing.rb                    # Main entry point
+├── rails_accessibility_testing/
 │   ├── version.rb
 │   ├── configuration.rb             # Config management
 │   ├── railtie.rb                   # Rails integration
 │   │
 │   ├── engine/
 │   │   ├── rule_engine.rb           # Core rule evaluator
-│   │   ├── violation_collector.rb   # Aggregates violations
-│   │   └── check_context.rb         # Context for checks
+│   │   ├── violation_collector.rb  # Aggregates violations
+│   │   └── violation.rb            # Violation data structure
 │   │
 │   ├── checks/
-│   │   ├── base_check.rb            # Base class for all checks
+│   │   ├── base_check.rb           # Base class for all checks
+│   │   │                            # (includes PartialDetection in 1.5.0)
 │   │   ├── form_labels_check.rb
 │   │   ├── image_alt_text_check.rb
 │   │   ├── interactive_elements_check.rb
-│   │   ├── heading_hierarchy_check.rb
+│   │   ├── heading_check.rb        # Renamed from heading_hierarchy_check
 │   │   ├── keyboard_accessibility_check.rb
 │   │   ├── aria_landmarks_check.rb
 │   │   ├── form_errors_check.rb
 │   │   ├── table_structure_check.rb
 │   │   ├── duplicate_ids_check.rb
 │   │   ├── skip_links_check.rb
-│   │   └── color_contrast_check.rb   # New
+│   │   └── color_contrast_check.rb
+│   │
+│   ├── accessibility_helper.rb      # Main helper module
+│   │                                # (includes PartialDetection, page cache)
+│   │
+│   ├── change_detector.rb          # Smart change detection
+│   │                                # (enhanced in 1.5.0 for assets/partials)
 │   │
 │   ├── integration/
 │   │   ├── rspec_integration.rb
 │   │   ├── minitest_integration.rb
-│   │   └── system_test_helper.rb    # Shared Capybara helpers
+│   │   └── system_test_helper.rb   # Shared Capybara helpers
 │   │
 │   ├── cli/
-│   │   ├── command.rb                # Main CLI command
-│   │   ├── url_scanner.rb            # Scans URLs/routes
-│   │   └── report_generator.rb       # Generates reports
+│   │   └── command.rb              # Main CLI command
 │   │
 │   ├── config/
-│   │   ├── yaml_loader.rb            # Loads YAML config
-│   │   ├── profile_manager.rb        # Manages profiles
-│   │   └── rule_override.rb          # Handles ignored rules
+│   │   └── yaml_loader.rb         # Loads YAML config
 │   │
-│   ├── errors/
-│   │   ├── error_message_builder.rb  # Formats error messages
-│   │   └── violation_formatter.rb   # Formats individual violations
+│   ├── error_message_builder.rb   # Formats error messages
+│   │                                # (enhanced with partial detection in 1.5.0)
 │   │
-│   └── utils/
-│       ├── view_file_detector.rb     # Detects view files
-│       └── wcag_reference.rb         # WCAG reference data
+│   └── middleware/
+│       └── page_visit_logger.rb
 │
 ├── generators/
 │   └── rails_a11y/
 │       └── install/
-│           ├── generator.rb
+│           ├── install_generator.rb
 │           └── templates/
 │               ├── initializer.rb.erb
-│               └── accessibility.yml.erb
+│               ├── accessibility.yml.erb
+│               └── all_pages_accessibility_spec.rb.erb
+│               # (enhanced in 1.5.0 with dynamic route discovery)
 │
 └── tasks/
-    └── accessibility.rake            # Rake tasks
+    └── accessibility.rake
 
 exe/
-└── rails_a11y                        # CLI executable
+├── rails_a11y                    # CLI executable
+├── rails_server_safe             # Safe server wrapper (NEW in 1.5.0)
+└── a11y_live_scanner            # Live scanner tool
 
 GUIDES/
 ├── getting_started.md
@@ -227,10 +329,9 @@ GUIDES/
 
 docs_site/
 ├── index.html
-├── usage.html
-├── configuration.html
-├── ci_integration.html
-└── contributing.html
+├── getting_started.md
+├── configuration.md
+└── ci_integration.md
 ```
 
 ---
@@ -240,11 +341,18 @@ docs_site/
 ### Adding Custom Checks
 
 ```ruby
-module RailsA11y
+module RailsAccessibilityTesting
   module Checks
     class CustomCheck < BaseCheck
+      def self.rule_name
+        :custom_check
+      end
+      
       def check
+        violations = []
         # Implementation
+        # Access to page, context, and partial detection methods
+        violations
       end
     end
   end
@@ -254,10 +362,11 @@ end
 ### Custom Error Formatters
 
 ```ruby
-module RailsA11y
-  module Errors
-    class CustomFormatter < ViolationFormatter
+module RailsAccessibilityTesting
+  class CustomFormatter
+    def format(violation)
       # Custom formatting logic
+      # Access to violation.element_context, violation.page_context
     end
   end
 end
@@ -281,10 +390,14 @@ ci:
 ## Performance Considerations
 
 1. **Lazy Loading**: Checks loaded only when needed
-2. **Caching**: View file detection cached
-3. **Parallel Execution**: Checks can run in parallel (future)
-4. **Selective Execution**: Only run checks for changed files (existing feature)
-5. **Configurable Depth**: Expensive checks behind flags
+2. **Caching**: 
+   - View file detection cached (implicit)
+   - **Page scanning cache** (NEW in 1.5.0): Prevents duplicate scans
+3. **Selective Execution**: 
+   - Only run checks for changed files (existing feature)
+   - **Smart change detection** (enhanced in 1.5.0)
+4. **Configurable Depth**: Expensive checks behind flags (color contrast)
+5. **Parallel Execution**: Checks can run in parallel (future)
 
 ---
 
@@ -294,6 +407,34 @@ ci:
 2. **Integration Tests**: Full Rails app with RSpec/Minitest
 3. **CLI Tests**: Test CLI against real Rails routes
 4. **Documentation Tests**: Ensure examples work
+5. **Performance Tests**: Verify caching and change detection work correctly
+
+---
+
+## Version 1.5.0 Highlights
+
+### New Components
+
+1. **PartialDetection Module**: Reusable partial detection logic
+2. **Page Scanning Cache**: Module-level cache for scanned pages
+3. **Enhanced ChangeDetector**: Asset change detection and smart partial impact analysis
+4. **Improved View File Detection**: Fuzzy matching and controller directory scanning
+5. **Rails Server Safe Wrapper**: Prevents Foreman from terminating processes
+
+### Enhanced Components
+
+1. **BaseCheck**: Now includes PartialDetection for better file location
+2. **AccessibilityHelper**: Includes page cache and partial detection
+3. **ErrorMessageBuilder**: Shows partial files in error messages
+4. **Generator Templates**: Dynamic route discovery and first-run logic
+5. **ChangeDetector**: Asset detection and improved partial impact analysis
+
+### Performance Improvements
+
+1. **Page Scanning Cache**: Eliminates duplicate scans
+2. **Smart Change Detection**: Only tests affected pages
+3. **First-Run Optimization**: Faster initial setup
+4. **Reduced Wait Times**: Faster Capybara operations
 
 ---
 
@@ -304,4 +445,22 @@ ci:
 3. **Performance Monitoring**: Track check performance
 4. **IDE Integration**: VS Code/IntelliJ plugins
 5. **CI/CD Templates**: Pre-built GitHub Actions, CircleCI configs
+6. **Parallel Check Execution**: Run checks in parallel for faster results
+7. **Incremental Reports**: Show only new issues since last run
+
+---
+
+## Migration Guide
+
+### From 1.4.x to 1.5.0
+
+1. **No breaking changes**: Fully backward compatible
+2. **Automatic benefits**: Existing installations get improved view detection automatically
+3. **Generator update**: Re-run `rails generate rails_a11y:install` to get latest spec template
+4. **CSV gem**: If using Ruby 3.3+, add `gem 'csv'` to Gemfile (generator handles this)
+5. **Config update**: `heading_hierarchy` renamed to `heading` in config (backward compatible)
+
+---
 
+**Architecture Version**: 1.5.0  
+**Last Updated**: 2025-11-19

data/CHANGELOG.md

@@ -5,6 +5,123 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2025-11-19
+
+### 🎉 Major Release: Enhanced View Detection & Performance Optimizations
+
+This release introduces significant improvements to view file detection, partial scanning, performance optimizations, and developer experience enhancements.
+
+### Added
+
+#### Smart View File Detection
+- **Intelligent view file matching**: Automatically detects view files even when action names don't match view file names (e.g., `search` action → `search_result.html.erb`)
+- **Controller directory scanning**: Scans all view files in controller directories to find matching templates
+- **Fuzzy matching**: Prefers files that start with the action name, handles variations like `search_result`, `search_results`, etc.
+- **Single view fallback**: If a controller has only one view file, automatically uses it (useful for single-action controllers)
+
+#### Advanced Partial Detection System
+- **Automatic partial discovery**: Scans view files to detect all rendered partials using multiple pattern matching
+- **Partial location detection**: Finds partials in controller directories, `shared/`, and `layouts/` directories
+- **Namespaced partial support**: Handles partials with paths like `layouts/navbar` or `shared/forms/input`
+- **Element-to-partial mapping**: When an accessibility issue is found, automatically determines if it's in a partial and shows the correct file path
+- **Multiple render pattern support**: Detects partials rendered via `render 'partial'`, `render partial: 'partial'`, ERB syntax, and more
+
+#### Performance Optimizations
+- **Page scanning cache**: Prevents duplicate accessibility scans of the same page during a test run
+- **Smart cache key**: Uses page path (preferred) or URL as cache key for efficient tracking
+- **Silent skip for cached pages**: Already-scanned pages are skipped silently without output
+- **Cache reset helper**: `reset_scanned_pages_cache` method for testing or forced rescans
+
+#### Change Detection Enhancements
+- **First-run detection**: Automatically tests all pages on first run, then only changed files on subsequent runs
+- **Marker file system**: Creates `.rails_a11y_initialized` marker file to track first run status
+- **Asset change detection**: Now detects changes in CSS (`app/assets/`) and JavaScript (`app/javascript/`) files
+- **Smart partial impact analysis**: When a partial changes, only tests pages that actually render that partial
+- **Layout vs partial distinction**: Main layout files trigger full retest, while specific partials only affect pages that use them
+- **Improved route-to-view mapping**: Better handling of routes with `GET|POST` verbs and complex route parameters
+
+#### Enhanced Error Reporting
+- **Accurate view file paths**: Error messages now show the exact view file or partial where issues occur
+- **Partial context in errors**: When an issue is in a partial, the error message shows both the partial file and the parent view
+- **Better route recognition**: Improved mapping of URLs to view files using Rails route recognition
+- **View file detection fallbacks**: Multiple fallback strategies ensure view files are found even in edge cases
+
+#### Developer Experience Improvements
+- **Friendly test summaries**: Enhanced summary output with passed/failed/skipped counts and reasons
+- **Progress indicators**: Real-time progress feedback during accessibility checks
+- **Suppressed verbose output**: Cleaner test output with less noise from skipped tests
+- **Timestamp formatting**: Human-readable timestamps (HH:MM:SS) in reports instead of full dates
+- **CSV warning suppression**: Automatic suppression of Ruby 3.3+ CSV deprecation warnings
+- **Better skip reasons**: Clear explanations for why tests are skipped (authentication required, page not found, etc.)
+
+#### Generator Enhancements
+- **Dynamic route discovery**: Generated `all_pages_accessibility_spec.rb` now dynamically discovers all GET routes at runtime
+- **Generic spec template**: Works for any Rails app without project-specific customization
+- **Smart Procfile.dev integration**: Automatically updates `Procfile.dev` with `rails_server_safe` for safe server management
+- **Conditional test execution**: Only runs tests when relevant files have changed
+- **First-run logic**: Ensures all pages are tested on initial run, then optimizes for subsequent runs
+
+#### Infrastructure Improvements
+- **Rails server safe wrapper**: New `rails_server_safe` executable prevents Foreman from terminating all processes when server is already running
+- **Improved Procfile.dev command**: More robust `a11y` command with better error handling and output filtering
+- **Better RSpec integration**: Enhanced `after(:suite)` hooks for comprehensive test summaries
+- **FactoryBot compatibility**: Conditional FactoryBot inclusion to prevent errors when not present
+
+### Changed
+
+#### Heading Check Improvements
+- **Renamed to `HeadingCheck`**: More comprehensive check covering all WCAG 2.1 AA heading requirements
+- **Multiple h1 detection**: Now correctly detects and reports multiple `<h1>` tags as errors (not warnings)
+- **Comprehensive heading validation**: Checks for missing h1, skipped heading levels, empty headings, and headings with images without alt text
+- **Better error messages**: More specific remediation steps for different heading hierarchy issues
+
+#### Skip Link Detection
+- **Enhanced pattern matching**: Detects skip links using multiple patterns (`skip-link`, `skiplink`, `href="#main"`, `href="#maincontent"`, etc.)
+- **Flexible selector support**: Works with various CSS classes and ID patterns commonly used for skip links
+
+#### Accessible Name Detection
+- **Image alt text in links**: Links containing images now properly use the image's alt text as the accessible name
+- **Better ARIA label handling**: Improved detection of accessible names via `aria-label` and `aria-labelledby`
+
+#### Error Message Formatting
+- **Unified output format**: Consistent error and warning formatting with timestamps and context
+- **Centralized reporting**: Errors shown first, then warnings, then success messages
+- **Removed confusing messages**: Eliminated "passed with warnings" message for clearer output
+
+### Fixed
+
+- **View file detection for `/items/search`**: Fixed issue where routes like `/items/search` (action: `search`, view: `search_result.html.erb`) weren't being detected
+- **Partial detection in layouts**: Fixed issue where partials in `layouts/` directory weren't being properly detected
+- **Change detection false positives**: Fixed issue where changing one partial was marking too many pages as affected
+- **Route parameter handling**: Better handling of routes with `GET|POST` verbs and multiple parameters
+- **CSV warnings in test environment**: Suppressed Ruby 3.3+ CSV deprecation warnings in both application and test environments
+- **Test result tracking**: Fixed issue where tests were showing "all passed" even when errors were present
+- **RSpec hook syntax**: Fixed `NoMethodError` with `RSpec.after(:suite)` by using correct `RSpec.configure` syntax
+- **FactoryBot loading**: Fixed `NameError` when FactoryBot is not present in the project
+
+### Improved
+
+- **Test execution speed**: Removed unnecessary `sleep` calls and reduced Capybara wait times
+- **Output readability**: Better formatting, emojis, and visual hierarchy in test output
+- **Documentation**: Comprehensive updates to README, ARCHITECTURE, and guides
+- **Code organization**: Better separation of concerns with `PartialDetection` module
+- **Error handling**: More robust error handling throughout the codebase
+
+### Technical Details
+
+- **New module**: `AccessibilityHelper::PartialDetection` for reusable partial detection logic
+- **Enhanced `BaseCheck`**: Now includes partial detection methods for better view file identification
+- **Cache mechanism**: Module-level `@scanned_pages` hash for efficient page tracking
+- **Improved `ChangeDetector`**: Enhanced logic for detecting file changes and their impact on pages
+- **Better route recognition**: Uses `Rails.application.routes.recognize_path` for accurate route-to-view mapping
+
+### Migration Notes
+
+- **No breaking changes**: This release is fully backward compatible
+- **Automatic upgrades**: Existing installations will automatically benefit from improved view detection
+- **Generator updates**: Re-running `rails generate rails_a11y:install` will update to the latest spec template
+- **CSV gem**: If using Ruby 3.3+, explicitly add `gem 'csv'` to your Gemfile (generator handles this)
+
 ## [1.4.3] - 2025-11-19
 
 ### Added
@@ -184,6 +301,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Compatible with RSpec Rails 6.0+
 - Modular architecture with rule engine and check definitions
 
+[1.5.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.5.0
 [1.4.3]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.3
 [1.4.2]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.2
 [1.4.1]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.1