ordit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 573d6f3d0536da9b396366f3c794b28b5c74161792ed2b107b9da4b4edc5c268
+  data.tar.gz: a806b40aaefc894a2cfea8caebc4f2c94f19ce87dcab0be01671bf9fd00f8c74
+SHA512:
+  metadata.gz: 4c3a5d96f70d1423f748db50052b37767eec553b5b6577ba18866040cb25d78457835aacbc478ed6169bcf379dea64ed4f743426144ce7e3288a3e854f9097ce
+  data.tar.gz: 0e30d715b13e47c0dd7c3362ee5917f6b1dfd40e9bdbffe1b590352af65791fd53383ddf222ebf982e41ae28d90ca3852557ff83fa03e873f9d44a757d15e73b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-12-12
+
+- 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 @@
+# Ordit
+
+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 'ordit'
+```
+
+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 ordit: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)
+```
+
+### Scan for Specific Controller Usage
+
+Find all uses of a specific controller:
+
+```bash
+rails audit:scan[controller_name]
+```
+
+Example:
+```bash
+rails audit:scan[products]
+rails audit:scan[users--name]  # For namespaced controllers
+```
+
+### Configuration
+
+You can customize the paths that are scanned in an initializer (`config/initializers/ordit.rb`):
+
+```ruby
+Ordit.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/lib/ordit/auditor.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Ordit
+  class Auditor
+    def initialize(config = Ordit.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 and convert underscores to hyphens
+          name = controller_path.join("--").gsub("_", "-")
+          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
+              match[0].split(/\s+/).each do |controller|
+                # Store controller names exactly as they appear in the view
+                # (they should already have hyphens as per Stimulus conventions)
+                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/ordit/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ordit
+  class Configuration
+    attr_accessor :view_paths, :controller_paths
+
+    def initialize
+      reset
+    end
+
+    def reset
+      base_path = Ordit.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/ordit/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Ordit
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "tasks/ordit.rake"
+    end
+
+    initializer "ordit.setup" do
+      require "ordit"
+    end
+  end
+end

data/lib/ordit/scanner.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Ordit
+  class Scanner
+    def initialize(config = Ordit.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/ordit/version.rb

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

data/lib/ordit.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "set"
+require "pathname"
+require_relative "ordit/version"
+require_relative "ordit/configuration"
+require_relative "ordit/auditor"
+require_relative "ordit/scanner"
+
+if defined?(Rails)
+  require "rails"
+  require 'ordit'
+  require "ordit/railtie"
+end
+
+module Ordit
+  class Error < StandardError; end
+
+  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/ordit.rake

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

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: ordit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Toby
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+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:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ordit.rb
+- lib/ordit/auditor.rb
+- lib/ordit/configuration.rb
+- lib/ordit/railtie.rb
+- lib/ordit/scanner.rb
+- lib/ordit/version.rb
+- lib/tasks/ordit.rake
+homepage: https://github.com/tobyond/ordit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tobyond/ordit
+  changelog_uri: https://github.com/tobyond/ordit/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/tobyond/ordit
+  bug_tracker_uri: https://github.com/tobyond/ordit/issues
+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: []