rails-css_unused 0.1.0 → 0.2.1

data/lib/rails/css_unused/view_scanner.rb

@@ -1,117 +1,324 @@
-# frozen_string_literal: true
-
-module Rails
-  module CssUnused
-    # Extracts CSS class names referenced in Rails views and components via regex.
-    # Dynamic classes (ERB interpolation) are only partially detected — see README.
-    class ViewScanner
-      # class="foo bar", class='foo', class: "foo", class: 'foo', class: %w[foo bar]
-      CLASS_ATTRIBUTE_PATTERN = /
-        class\s*=\s*["']([^"']+)["']
-        |
-        class:\s*["']([^"']+)["']
-        |
-        class:\s*%w\[\s*([^\]]+)\]
-        |
-        class:\s*\[\s*([^\]]+)\]
-      /ix
-
-      # HAML: .foo.bar or %div.foo
-      HAML_CLASS_PATTERN = /\.([a-zA-Z_][\w-]*)/
-
-      # Tailwind-style @apply or data-class rarely; common helper: tag.div class: "x"
-      TAG_HELPER_CLASS_PATTERN = /(?:^|\s)class:\s*["']([^"']+)["']/m
-
-      def initialize(root:, config: CssUnused.configuration)
-        @root = Pathname(root)
-        @config = config
-      end
-
-      def used_classes
-        classes = Set.new
-        each_view_file { |path, content| classes.merge(extract_from(content, path)) }
-        classes.subtract(normalized_ignore_list)
-        classes
-      end
-
-      private
-
-      def each_view_file
-        paths = @config.view_paths + @config.component_paths
-        extensions = (Configuration::VIEW_EXTENSIONS + Configuration::COMPONENT_EXTENSIONS).uniq
-
-        paths.each do |relative|
-          dir = @root.join(relative)
-          next unless dir.directory?
-
-          Dir.glob(dir.join("**", "*")).each do |file|
-            path = Pathname(file)
-            next unless path.file?
-            next unless extensions.include?(path.extname) || compound_extension?(path)
-
-            yield path, path.read(encoding: Encoding::UTF_8)
-          rescue ArgumentError
-            yield path, path.read
-          end
-        end
-      end
-
-      def compound_extension?(path)
-        name = path.basename.to_s
-        Configuration::VIEW_EXTENSIONS.any? { |ext| name.end_with?(ext) }
-      end
-
-      def extract_from(content, path)
-        found = Set.new
-        content.scan(CLASS_ATTRIBUTE_PATTERN).flatten.compact.each do |chunk|
-          found.merge(tokenize_class_value(chunk))
-        end
-        content.scan(TAG_HELPER_CLASS_PATTERN) { |m| found.merge(tokenize_class_value(m[0])) }
-        if haml_file?(path)
-          content.scan(HAML_CLASS_PATTERN) { |m| found << m[0] unless haml_false_positive?(m[0]) }
-        end
-        found.merge(extract_erb_interpolated_classes(content))
-        found
-      end
-
-      def haml_file?(path)
-        path.extname == ".haml" || path.to_s.end_with?(".html.haml")
-      end
-
-      # Skip decimal numbers like .5 in HAML (rare in class position but possible in CSS snippets)
-      def haml_false_positive?(token)
-        token.match?(/\A\d/)
-      end
-
-      def tokenize_class_value(raw)
-        raw
-          .gsub(/['"]/, " ")
-          .split(/[\s,]+/)
-          .map { |t| t.strip.sub(/\A\./, "") }
-          .reject(&:empty?)
-          .reject { |t| t.include?("<%") || t.include?('#{') }
-          .select { |t| valid_class_token?(t) }
-      end
-
-      def valid_class_token?(token)
-        token.match?(/\A[a-zA-Z_][\w-]*\z/) || token.match?(/\A[a-zA-Z_][\w-]*--[\w-]+\z/)
-      end
-
-      # Picks up literal segments inside ERB-interpolated class attributes when present.
-      def extract_erb_interpolated_classes(content)
-        found = Set.new
-        content.scan(/class\s*=\s*["'][^"']*<%=[^%]+%>[^"']*["']/m) do
-          literal = Regexp.last_match(0)
-          literal.gsub(/<%.*?%>/m, " ").scan(/["']([^"']+)["']/) do |part|
-            found.merge(tokenize_class_value(part[0]))
-          end
-        end
-        found
-      end
-
-      def normalized_ignore_list
-        @config.ignore_classes.map(&:to_s)
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    # Scans Rails view templates, ViewComponent files, Phlex components,
+    # Stimulus controllers, and Ruby files for referenced CSS class names.
+    #
+    # Handles:
+    #   ERB:       class="foo bar",  class: "foo",  class: ["foo", "bar"]
+    #   HAML:      .foo.bar,  %div.foo
+    #   Slim:      div.foo,  .foo
+    #   Ruby:      html_class: "foo",  css_classes("foo bar"),  "foo bar"
+    #   Stimulus:  this.element.classList.add("foo"),  "foo" string literals
+    #   Dynamic:   class="<%= cond ? 'foo' : 'bar' %>" — literal parts extracted
+    #   Dynamic vars: status_class = "foo-bar" — string assigned to *_class/*_classes var
+    class ViewScanner
+      # ── ERB / HTML patterns ──────────────────────────────────────────────
+      # class="foo bar baz"  or  class='foo bar'
+      HTML_CLASS_ATTR   = /class\s*=\s*["']([^"'<>]+)["']/i
+      # class: "foo bar"  or  class: 'foo'
+      RUBY_CLASS_KV     = /class:\s*["']([^"']+)["']/
+      # class: ["foo", "bar"]  or  class: %w[foo bar]
+      RUBY_CLASS_ARRAY  = /class:\s*(?:\[|%w\[)\s*([^\]\n]+)/
+      # tag.div(class: "foo")  content_tag(:div, class: "foo")
+      TAG_HELPER        = /(?:content_tag|tag\.\w+)\s*[({][^)}\n]*class:\s*["']([^"']+)["']/
+
+      # ── HAML patterns ───────────────────────────────────────────────────
+      # .foo, %div.foo.bar, %span.foo#id
+      HAML_IMPLICIT     = /^[ \t]*(?:%[\w:-]+)?(\.[a-zA-Z][a-zA-Z0-9_-]*(?:\.[a-zA-Z][a-zA-Z0-9_-]*)*)/
+      # Inline { class: "foo" }
+      HAML_HASH_CLASS   = /class:\s*["']([^"']+)["']/
+
+      # ── Slim patterns ───────────────────────────────────────────────────
+      # div.foo.bar or .foo.bar on its own line
+      SLIM_CLASS        = /^[ \t]*(?:[\w-]*)(\.[a-zA-Z][a-zA-Z0-9_-]*(?:\.[a-zA-Z][a-zA-Z0-9_-]*)*)/
+
+      # ── ERB dynamic interpolation ────────────────────────────────────────
+      # class="<%= expr %>", class="prefix-<%= var %>"  — extracts static parts
+      ERB_DYNAMIC_CLASS = /class\s*=\s*["'][^"']*<%=[^%]+%>[^"']*["']/m
+
+      # ── Dynamic class variable detection (v0.2.1) ────────────────────────
+      # Detects string literals assigned to variables whose name ends with
+      # _class, _classes, _style, or _css — and the string contains hyphens
+      # (Ruby variable names cannot contain hyphens, so it must be a value).
+      #
+      # Matches patterns like:
+      #   status_class = "foo-bar"
+      #   button_classes = "btn btn-primary"
+      #   ["Active", "status-active"]          (array element with hyphenated string)
+      #   ["Cancelled", "status-cancelled"]
+      #
+      # Rule: any double- or single-quoted string containing at least one
+      # hyphen is unambiguously a string value (not a Ruby identifier), so
+      # we can safely extract it as a potential class name.
+      #
+      # Pattern 1: variable ending in _class/_classes/_style/_css = "value"
+      DYNAMIC_CLASS_VAR = /\b\w+_(?:class(?:es)?|style|css)\s*=\s*["']([^"'\n]+)["']/
+      #
+      # Pattern 2: any quoted string with hyphens in array/tuple context
+      # e.g. ["Active", "status-active"] — the hyphenated strings are CSS classes
+      HYPHENATED_STRING = /["']([a-zA-Z][a-zA-Z0-9]*(?:-[a-zA-Z0-9]+)+)["']/
+
+      # ── Ruby / Stimulus string literals ─────────────────────────────────
+      # Any double-quoted string that looks like a space-separated class list
+      JS_ADD_CLASS      = /(?:classList\.add|classList\.toggle|classList\.replace)\s*\(\s*["']([^"']+)["']/
+      JS_REMOVE_CLASS   = /(?:classList\.remove)\s*\(\s*["']([^"']+)["']/
+      RUBY_STRING_CLASSES = /["']([a-zA-Z][a-zA-Z0-9_-]*(?:\s+[a-zA-Z][a-zA-Z0-9_-]*)*)[\"']/
+
+      def initialize(root:, config: CssUnused.configuration)
+        @root   = Pathname(root)
+        @config = config
+      end
+
+      # Returns a Set of class name strings referenced across all view files.
+      def used_classes
+        classes     = Set.new
+        ignore_set  = @config.ignore_classes.map(&:to_s).to_set
+        ignore_pats = Array(@config.ignore_patterns)
+
+        each_view_file do |path, content|
+          extract_from(content, path).each do |cls|
+            next if ignore_set.include?(cls)
+            next if ignore_pats.any? { |p| cls.match?(p) }
+            classes << cls
+          end
+        end
+
+        if @config.scan_javascript_for_classes
+          each_js_file do |path, content|
+            extract_js_classes(content).each { |cls| classes << cls }
+          end
+        end
+
+        classes
+      end
+
+      private
+
+      # ── File iteration ───────────────────────────────────────────────────
+
+      def each_view_file
+        paths = (@config.view_paths + @config.component_paths).uniq
+        paths.each do |rel|
+          dir = @root.join(rel)
+          next unless dir.directory?
+
+          Dir.glob(dir.join("**", "*")).each do |f|
+            path = Pathname(f)
+            next unless path.file? && view_file?(path)
+
+            content = safe_read(path)
+            yield path, content if content
+          end
+        end
+      end
+
+      def each_js_file
+        @config.javascript_paths.each do |rel|
+          dir = @root.join(rel)
+          next unless dir.directory?
+
+          Dir.glob(dir.join("**", "*.{js,ts,jsx,tsx}")).each do |f|
+            path    = Pathname(f)
+            content = safe_read(path)
+            yield path, content if content
+          end
+        end
+
+        return unless @config.scan_ruby_components
+
+        @config.component_paths.each do |rel|
+          dir = @root.join(rel)
+          next unless dir.directory?
+
+          Dir.glob(dir.join("**", "*.rb")).each do |f|
+            path    = Pathname(f)
+            content = safe_read(path)
+            yield path, content if content
+          end
+        end
+      end
+
+      def view_file?(path)
+        name = path.basename.to_s
+        Configuration::VIEW_EXTENSIONS.any? { |ext| name.end_with?(ext) } ||
+          Configuration::COMPOUND_VIEW_ENDINGS.any? { |ext| name.end_with?(ext) }
+      end
+
+      # ── Class extraction ─────────────────────────────────────────────────
+
+      def extract_from(content, path)
+        found = Set.new
+        ext   = path.extname
+        base  = path.basename.to_s
+
+        if ext == ".erb" || base.end_with?(".html.erb")
+          found.merge extract_erb(content)
+        end
+
+        if ext == ".haml" || base.end_with?(".html.haml")
+          found.merge extract_haml(content)
+        end
+
+        if ext == ".slim" || base.end_with?(".html.slim")
+          found.merge extract_slim(content)
+        end
+
+        if ext == ".rb"
+          found.merge extract_ruby(content)
+        end
+
+        found
+      end
+
+      def extract_erb(content)
+        found = Set.new
+
+        # Standard class attributes
+        [HTML_CLASS_ATTR, RUBY_CLASS_KV, TAG_HELPER].each do |pat|
+          content.scan(pat) { |m| found.merge tokenize(m[0]) }
+        end
+
+        # class: ["foo", "bar"]  /  class: %w[foo bar]
+        content.scan(RUBY_CLASS_ARRAY) do |m|
+          found.merge tokenize(m[0].gsub(/["',]/, " "))
+        end
+
+        # ERB dynamic class attributes — extract static string parts
+        content.scan(ERB_DYNAMIC_CLASS) do
+          chunk = Regexp.last_match(0)
+          stripped = chunk.gsub(/<%.*?%>/m, " ")
+          stripped.scan(/["']([^"']+)["']/) { |m| found.merge tokenize(m[0]) }
+        end
+
+        # ── v0.2.1: Dynamic class variable detection ──────────────────────
+        # Detects: status_class = "foo-bar" or button_classes = "btn btn-primary"
+        found.merge extract_dynamic_class_vars(content)
+
+        found
+      end
+
+      def extract_haml(content)
+        found = Set.new
+
+        content.scan(HAML_IMPLICIT) do |m|
+          m[0].split(".").reject(&:empty?).each do |cls|
+            found << cls if valid_class?(cls)
+          end
+        end
+
+        content.scan(HAML_HASH_CLASS) { |m| found.merge tokenize(m[0]) }
+        content.scan(RUBY_CLASS_KV)   { |m| found.merge tokenize(m[0]) }
+
+        # v0.2.1: detect dynamic class vars in HAML Ruby blocks too
+        found.merge extract_dynamic_class_vars(content)
+
+        found
+      end
+
+      def extract_slim(content)
+        found = Set.new
+
+        content.scan(SLIM_CLASS) do |m|
+          m[0].split(".").reject(&:empty?).each do |cls|
+            found << cls if valid_class?(cls)
+          end
+        end
+
+        content.scan(RUBY_CLASS_KV) { |m| found.merge tokenize(m[0]) }
+
+        # v0.2.1: detect dynamic class vars in Slim Ruby blocks too
+        found.merge extract_dynamic_class_vars(content)
+
+        found
+      end
+
+      def extract_ruby(content)
+        found = Set.new
+
+        content.scan(RUBY_CLASS_KV)   { |m| found.merge tokenize(m[0]) }
+        content.scan(RUBY_CLASS_ARRAY) { |m| found.merge tokenize(m[0].gsub(/["',]/, " ")) }
+
+        content.scan(RUBY_STRING_CLASSES) do |m|
+          tokens = tokenize(m[0])
+          found.merge(tokens) if tokens.all? { |t| valid_class?(t) }
+        end
+
+        # v0.2.1: detect dynamic class vars in Ruby component files
+        found.merge extract_dynamic_class_vars(content)
+
+        found
+      end
+
+      def extract_js_classes(content)
+        found = Set.new
+        content.scan(JS_ADD_CLASS)    { |m| found.merge tokenize(m[0]) }
+        content.scan(JS_REMOVE_CLASS) { |m| found.merge tokenize(m[0]) }
+        found
+      end
+
+      # ── v0.2.1: Smart dynamic class variable extraction ──────────────────
+      #
+      # Scans content for two patterns:
+      #
+      # 1. Variables named *_class, *_classes, *_style, *_css assigned a string:
+      #      status_class = "foo-bar"        => extracts "foo-bar"
+      #      button_classes = "btn btn-sm"   => extracts "btn", "btn-sm"
+      #
+      # 2. Any quoted string containing a hyphen (unambiguous: Ruby variable
+      #    names cannot contain hyphens, so hyphenated quoted strings MUST be
+      #    string values, never variable names):
+      #      ["Active", "status-active"]     => extracts "status-active"
+      #      ["Cancelled", "status-cancelled"] => extracts "status-cancelled"
+      #
+      # This directly solves the false-positive problem where classes like
+      # status-approved, status-cancelled, status-requested were flagged as
+      # ghost classes because they were assigned to a variable (status_class)
+      # and used via <%= status_class %> interpolation.
+      def extract_dynamic_class_vars(content)
+        found = Set.new
+
+        # Pattern 1: *_class/*_classes variable assignments
+        content.scan(DYNAMIC_CLASS_VAR) do |m|
+          tokenize(m[0]).each { |cls| found << cls if valid_class?(cls) }
+        end
+
+        # Pattern 2: hyphenated string literals (unambiguously CSS class values)
+        content.scan(HYPHENATED_STRING) do |m|
+          cls = m[0].strip
+          found << cls if valid_class?(cls)
+        end
+
+        found
+      end
+
+      # ── Helpers ───────────────────────────────────────────────────────────
+
+      def tokenize(raw)
+        return Set.new if raw.nil?
+
+        raw
+          .gsub(/["']/, " ")
+          .split(/[\s,]+/)
+          .map { |t| t.strip.delete_prefix(".") }
+          .reject(&:empty?)
+          .reject { |t| t.include?("<%") || t.include?('#{') }
+          .select { |t| valid_class?(t) }
+          .to_set
+      end
+
+      def valid_class?(token)
+        token.match?(/\A-?[a-zA-Z_][a-zA-Z0-9_-]*\z/)
+      end
+
+      def safe_read(path)
+        path.read(encoding: "UTF-8")
+      rescue ArgumentError, Encoding::UndefinedConversionError
+        path.read(encoding: "BINARY").encode("UTF-8", invalid: :replace, undef: :replace)
+      rescue Errno::ENOENT, Errno::EACCES
+        nil
+      end
+    end
+  end
+end

data/lib/rails/css_unused.rb

@@ -1,36 +1,40 @@
-# frozen_string_literal: true
-
-require "pathname"
-require "set"
-
-require_relative "css_unused/version"
-require_relative "css_unused/configuration"
-require_relative "css_unused/view_scanner"
-require_relative "css_unused/stylesheet_scanner"
-require_relative "css_unused/report"
-
-module Rails
-  module CssUnused
-    class Error < StandardError; end
-
-    class << self
-      def report(root: default_root, output: $stdout)
-        Report.new(root: root, output: output).print_summary
-      end
-
-      def ghost_classes(root: default_root)
-        Report.new(root: root).ghost_classes.map(&:class_name)
-      end
-
-      def default_root
-        if defined?(Rails) && Rails.respond_to?(:root)
-          Rails.root
-        else
-          Pathname.new(Dir.pwd)
-        end
-      end
-    end
-  end
-end
-
-require_relative "css_unused/railtie" if defined?(Rails::Railtie)
+# frozen_string_literal: true
+
+require "pathname"
+require "set"
+
+require_relative "css_unused/version"
+require_relative "css_unused/configuration"
+require_relative "css_unused/stylesheet_scanner"
+require_relative "css_unused/view_scanner"
+require_relative "css_unused/report"
+
+module Rails
+  module CssUnused
+    class Error < StandardError; end
+
+    class << self
+      # Prints a full report to output (default: $stdout).
+      # Returns the exit code (0 = clean, 1 = ghosts found + fail_on_unused).
+      def report(root: default_root, output: $stdout)
+        Report.new(root: root, output: output).print_summary
+      end
+
+      # Returns an array of unused class name strings.
+      def ghost_classes(root: default_root)
+        Report.new(root: root).ghost_classes.map(&:class_name)
+      end
+
+      # Returns the project root: Rails.root if inside Rails, else cwd.
+      def default_root
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          ::Rails.root
+        else
+          Pathname.new(Dir.pwd)
+        end
+      end
+    end
+  end
+end
+
+require_relative "css_unused/railtie" if defined?(Rails::Railtie)

data/lib/rails-css_unused.rb

@@ -1,3 +1,6 @@
-# frozen_string_literal: true
-
-require_relative "rails/css_unused"
+# frozen_string_literal: true
+
+# Compatibility shim — allows both:
+#   require "rails/css_unused"
+#   require "rails-css_unused"
+require_relative "rails/css_unused"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-css_unused
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - sghani001
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -59,9 +59,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.12'
 description: |
-  A lightweight Rake task that regex-scans views and components for CSS class
-  references, compares them to selectors in your stylesheets, and reports
-  ghost classes defined in CSS but never used in templates.
+  rails-css_unused scans your stylesheets (CSS/SCSS/Sass) and all view templates
+  (ERB, HAML, Slim), ViewComponents, Phlex components, and Stimulus JS controllers
+  to report CSS class selectors that are defined but never referenced. Supports
+  BEM naming, dynamic class detection, source-file attribution, CI exit codes,
+  and configurable ignore lists — zero runtime overhead.
 email:
 - sghani001@users.noreply.github.com
 executables: []
@@ -76,6 +78,7 @@ files:
 - lib/rails/css_unused/configuration.rb
 - lib/rails/css_unused/railtie.rb
 - lib/rails/css_unused/report.rb
+- lib/rails/css_unused/spinner.rb
 - lib/rails/css_unused/stylesheet_scanner.rb
 - lib/rails/css_unused/tasks.rake
 - lib/rails/css_unused/version.rb
@@ -107,5 +110,5 @@ requirements: []
 rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
-summary: Find unused CSS classes in Rails apps via static analysis
+summary: Find unused CSS classes in Rails apps — fast, accurate static analysis
 test_files: []