Stimulus Audit

A Ruby gem to analyze Stimulus.js controller usage in your Rails application. Find unused controllers, undefined controllers, and audit your Stimulus controller usage.

Add this line to your application's Gemfile:

gem 'stimulus-audit'

And then execute:

bundle install

Run an audit to see all defined and used controllers in your application:

rails audit:stimulus

This will show:

• Controllers that are defined but never used
• Controllers that are used but don't have corresponding files
• Active controllers and where they're being used
• Summary statistics

Example output:

📊 Stimulus Controller Audit

❌ Defined but unused controllers:
   unused_feature
   └─ app/javascript/controllers/unused_feature_controller.js

⚠️  Used but undefined controllers:
   missing_controller
   └─ app/views/products/show.html.erb (lines: 15, 23)

✅ Active controllers:
   products
   └─ Defined in: app/javascript/controllers/products_controller.js
   └─ Used in:
      └─ app/views/products/index.html.erb (lines: 10, 45)
      └─ app/components/product_card/component.html.erb (lines: 3)

Find all uses of a specific controller:

rails audit:scan[controller_name]

Example:

rails audit:scan[products]
rails audit:scan[users--name]  # For namespaced controllers

You can customize the paths that are scanned in an initializer (config/initializers/stimulus_audit.rb):

StimulusAudit.configure do |config|
  config.view_paths = [
    Rails.root.join('app/views/**/*.{html,erb,haml}'),
    Rails.root.join('app/javascript/**/*.{js,jsx}'),
    Rails.root.join('app/components/**/*.{html,erb,haml,rb}')
  ]
  
  config.controller_paths = [
    Rails.root.join('app/javascript/controllers/**/*.{js,ts}')
  ]
end

• Finds unused Stimulus controllers
• Detects controllers used in views but missing controller files
• Supports namespaced controllers (e.g., users--name)
• Handles multiple syntax styles:

  # HTML attribute syntax
  <div data-controller="products">
  
  # Ruby hash syntax
  <%= f.submit 'Save', data: { controller: 'products' } %>
  
  # Hash rocket syntax
  <%= f.submit 'Save', data: { :controller => 'products' } %>

• Scans ERB, HTML, and HAML files
• Works with both JavaScript and TypeScript controller files
• Supports component-based architectures

After checking out the repo:

1. Run bundle install to install dependencies
2. Run rake test to run the tests
3. Create a branch for your changes (git checkout -b my-new-feature)
4. Make your changes and add tests
5. Ensure tests pass

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.

The gem is available as open source under the terms of the MIT License.