stimulus-audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d97ee4d76118febf8f6d72f4434bdcef35e925dd5871bbc624bfb221e0cd0fd3
+  data.tar.gz: a54d0519141cced0080073a8713ae0d923e0452b0203817543cc1b99ed95c44d
+SHA512:
+  metadata.gz: '0458a1420dfd0419ceefe18b4a70e8ba676690c99e700b21a594cedf7d397f41ac884555233fb6bf6dccf9e13bfc48f7f7f54b3dcd5cb30badb71ce387f42b89'
+  data.tar.gz: 67e254902d28bdf8abfa7d268cc6f603ffe6893420c7fab4652d9eed3b2cac0c5cd8899cf0387da938b25fb007db7fff8068f70215b7a4164da4d1108222a459

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-12-11
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 TODO: Write your name
+
+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.

data/README.md

@@ -0,0 +1,122 @@
+# 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'stimulus-audit'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+## Usage
+
+### Audit All Controllers
+
+Run an audit to see all defined and used controllers in your application:
+
+```bash
+rails stimulus:audit
+```
+
+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)
+```
+
+### Scan for Specific Controller Usage
+
+Find all uses of a specific controller:
+
+```bash
+rails stimulus:scan[controller_name]
+```
+
+Example:
+```bash
+rails stimulus:scan[products]
+rails stimulus:scan[users--name]  # For namespaced controllers
+```
+
+### Configuration
+
+You can customize the paths that are scanned in an initializer (`config/initializers/stimulus_audit.rb`):
+
+```ruby
+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
+```
+
+## Features
+
+- Finds unused Stimulus controllers
+- Detects controllers used in views but missing controller files
+- Supports namespaced controllers (e.g., `users--name`)
+- Handles multiple syntax styles:
+  ```ruby
+  # 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
+
+## Development
+
+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
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/stimulus_audit/auditor.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module StimulusAudit
+  class Auditor
+    def initialize(config = StimulusAudit.configuration)
+      @config = config
+    end
+
+    def audit
+      defined_controllers = find_defined_controllers
+      used_controllers = find_used_controllers
+
+      AuditResult.new(
+        defined_controllers: defined_controllers,
+        used_controllers: used_controllers,
+        controller_locations: find_controller_locations,
+        usage_locations: find_usage_locations
+      )
+    end
+
+    private
+
+    def find_defined_controllers
+      controllers = Set.new
+      @config.controller_paths.each do |path|
+        Dir.glob(path.to_s).each do |file|
+          # Extract relative path from controllers directory
+          full_path = Pathname.new(file)
+          controllers_dir = full_path.each_filename.find_index("controllers")
+
+          next unless controllers_dir
+
+          # Get path components after 'controllers'
+          controller_path = full_path.each_filename.to_a[(controllers_dir + 1)..]
+          # Remove _controller.js from the last component
+          controller_path[-1] = controller_path[-1].sub(/_controller\.(js|ts)$/, "")
+          # Join with -- for namespacing
+          name = controller_path.join("--")
+          controllers << name
+        end
+      end
+      controllers
+    end
+
+    def find_used_controllers
+      controllers = Set.new
+      patterns = [
+        /data-controller=["']([^"']+)["']/, # HTML attribute syntax
+        /data:\s*{\s*(?:controller:|:controller\s*=>)\s*["']([^"']+)["']/ # Both hash syntaxes
+      ]
+
+      @config.view_paths.each do |path|
+        Dir.glob(path.to_s).each do |file|
+          content = File.read(file)
+          patterns.each do |pattern|
+            content.scan(pattern) do |match|
+              # Split in case of multiple controllers: "users--name list toggle"
+              match[0].split(/\s+/).each do |controller|
+                controllers << controller
+              end
+            end
+          end
+        end
+      end
+      controllers
+    end
+
+    def find_controller_locations
+      locations = {}
+      @config.controller_paths.each do |path_pattern|
+        Dir.glob(path_pattern).each do |file|
+          relative_path = Pathname.new(file).relative_path_from(Dir.pwd)
+          controller_path = relative_path.to_s.gsub(%r{^app/javascript/controllers/|_controller\.(js|ts)$}, "")
+          name = controller_path.gsub("/", "--")
+          locations[name] = relative_path
+        end
+      end
+      locations
+    end
+
+    def find_usage_locations
+      locations = Hash.new { |h, k| h[k] = {} }
+      patterns = [
+        /data-controller=["']([^"']+)["']/,
+        /data:\s*{(?:[^}]*\s)?controller:\s*["']([^"']+)["']/,
+        /data:\s*{(?:[^}]*\s)?controller\s*=>\s*["']([^"']+)["']/
+      ]
+
+      @config.view_paths.each do |path_pattern|
+        Dir.glob(path_pattern).each do |file|
+          File.readlines(file).each_with_index do |line, index|
+            patterns.each do |pattern|
+              line.scan(pattern) do |match|
+                match[0].split(/\s+/).each do |controller|
+                  relative_path = Pathname.new(file).relative_path_from(Dir.pwd)
+                  locations[controller][relative_path] ||= []
+                  locations[controller][relative_path] << index + 1
+                end
+              end
+            end
+          end
+        end
+      end
+      locations
+    end
+  end
+
+  class AuditResult
+    attr_reader :defined_controllers, :used_controllers,
+                :controller_locations, :usage_locations
+
+    def initialize(defined_controllers:, used_controllers:,
+                   controller_locations:, usage_locations:)
+      @defined_controllers = defined_controllers
+      @used_controllers = used_controllers
+      @controller_locations = controller_locations
+      @usage_locations = usage_locations
+    end
+
+    def unused_controllers
+      defined_controllers - used_controllers
+    end
+
+    def undefined_controllers
+      used_controllers - defined_controllers
+    end
+
+    def active_controllers
+      defined_controllers & used_controllers
+    end
+
+    def to_console
+      puts "\n📊 Stimulus Controller Audit\n"
+
+      if unused_controllers.any?
+        puts "\n❌ Defined but unused controllers:"
+        unused_controllers.sort.each do |controller|
+          puts "   #{controller}"
+          puts "   └─ #{controller_locations[controller]}"
+        end
+      end
+
+      if undefined_controllers.any?
+        puts "\n⚠️  Used but undefined controllers:"
+        undefined_controllers.sort.each do |controller|
+          puts "   #{controller}"
+          usage_locations[controller].each do |file, lines|
+            puts "   └─ #{file} (lines: #{lines.join(", ")})"
+          end
+        end
+      end
+
+      if active_controllers.any?
+        puts "\n✅ Active controllers:"
+        active_controllers.sort.each do |controller|
+          puts "   #{controller}"
+          puts "   └─ Defined in: #{controller_locations[controller]}"
+          puts "   └─ Used in:"
+          usage_locations[controller].each do |file, lines|
+            puts "      └─ #{file} (lines: #{lines.join(", ")})"
+          end
+        end
+      end
+
+      puts "\n📈 Summary:"
+      puts "   Total controllers defined: #{defined_controllers.size}"
+      puts "   Total controllers in use:  #{used_controllers.size}"
+      puts "   Unused controllers:        #{unused_controllers.size}"
+      puts "   Undefined controllers:     #{undefined_controllers.size}"
+      puts "   Properly paired:           #{active_controllers.size}"
+    end
+  end
+end

data/lib/stimulus_audit/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module StimulusAudit
+  class Configuration
+    attr_accessor :view_paths, :controller_paths
+
+    def initialize
+      reset
+    end
+
+    def reset
+      base_path = StimulusAudit.root
+
+      @view_paths = [
+        base_path.join('app/views/**/*.{html,erb,haml}').to_s,
+        base_path.join('app/javascript/**/*.{js,jsx}').to_s,
+        base_path.join('app/components/**/*.{html,erb,haml,rb}').to_s
+      ]
+
+      @controller_paths = [
+        base_path.join('app/javascript/controllers/**/*.{js,ts}').to_s
+      ]
+    end
+  end
+end

data/lib/stimulus_audit/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module StimulusAudit
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "tasks/stimulus_audit.rake"
+    end
+  end
+end

data/lib/stimulus_audit/scanner.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StimulusAudit
+  class Scanner
+    def initialize(config = StimulusAudit.configuration)
+      @config = config
+    end
+
+    def scan(controller)
+      matches = find_matches(controller)
+      print_results(controller, matches)
+    end
+
+    private
+
+    def find_matches(controller)
+      matches = []
+      patterns = [
+        /data-controller=["'](?:[^"']*\s)?#{Regexp.escape(controller)}(?:\s[^"']*)?["']/, # HTML attribute
+        /data:\s*{\s*(?:controller:|:controller\s*=>)\s*["'](?:[^"']*\s)?#{Regexp.escape(controller)}(?:\s[^"']*)?["']/ # Both hash syntaxes
+      ]
+
+      @config.view_paths.each do |path|
+        Dir.glob(path.to_s).each do |file|
+          content = File.readlines(file)
+          content.each_with_index do |line, index|
+            next unless patterns.any? { |pattern| line.match?(pattern) }
+
+            matches << {
+              file: Pathname.new(file).relative_path_from(Pathname.new(Dir.pwd)),
+              line_number: index + 1,
+              content: line.strip
+            }
+          end
+        end
+      end
+      matches
+    end
+
+    def print_results(controller, matches)
+      puts "\nSearching for stimulus controller: '#{controller}'\n\n"
+
+      if matches.empty?
+        puts "No matches found."
+        return
+      end
+
+      current_file = nil
+      matches.each do |match|
+        if current_file != match[:file]
+          puts "📁 #{match[:file]}"
+          current_file = match[:file]
+        end
+        puts "   Line #{match[:line_number]}:"
+        puts "      #{match[:content]}\n\n"
+      end
+    end
+  end
+end

data/lib/stimulus_audit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StimulusAudit
+  VERSION = "0.1.0"
+end

data/lib/stimulus_audit.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'pathname'
+require "stimulus_audit/version"
+require "stimulus_audit/configuration"
+require "stimulus_audit/auditor"
+require "stimulus_audit/scanner"
+
+if defined?(Rails)
+  require "rails"
+  require "stimulus_audit/railtie" 
+end
+
+module StimulusAudit
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def root
+      if defined?(Rails)
+        Rails.root
+      else
+        Pathname.new(Dir.pwd)
+      end
+    end
+  end
+end

data/lib/tasks/stimulus_audit.rake

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+namespace :stimulus do
+  desc "Audit Stimulus controllers usage and find orphaned controllers"
+  task audit: :environment do
+    StimulusAudit::Auditor.new.audit.to_console
+  end
+
+  desc "Scan files for stimulus controller usage (e.g., rake stimulus:scan[users--name])"
+  task :scan, [:controller] => :environment do |_, args|
+    controller = args[:controller]
+    if controller.nil? || controller.empty?
+      puts "Please provide a controller name: rake stimulus:scan[controller_name]"
+      next
+    end
+
+    StimulusAudit::Scanner.new.scan(controller)
+  end
+end

data/sig/stimulus_audit.rbs

@@ -0,0 +1,4 @@
+module StimulusAudit
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: stimulus-audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Toby
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-12-11 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby gem to analyze usage of Stimulus controllers, finding unused controllers
+  and undefined controllers
+email:
+- toby@darkroom.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/stimulus_audit.rb
+- lib/stimulus_audit/auditor.rb
+- lib/stimulus_audit/configuration.rb
+- lib/stimulus_audit/railtie.rb
+- lib/stimulus_audit/scanner.rb
+- lib/stimulus_audit/version.rb
+- lib/tasks/stimulus_audit.rake
+- sig/stimulus_audit.rbs
+homepage: https://github.com/yourusername/stimulus-audit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yourusername/stimulus-audit
+  source_code_uri: https://github.com/yourusername/stimulus-audit
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Audit Stimulus.js controllers in your Rails application
+test_files: []