rails-css_unused 0.1.0 → 0.2.1

data/lib/rails/css_unused/report.rb

@@ -1,50 +1,111 @@
-# frozen_string_literal: true
-
-module Rails
-  module CssUnused
-    class Report
-      Ghost = Struct.new(:class_name, keyword_init: true)
-
-      def initialize(root:, output: $stdout, config: CssUnused.configuration)
-        @root = Pathname(root)
-        @output = output
-        @config = config
-      end
-
-      def ghost_classes
-        used = ViewScanner.new(root: @root, config: @config).used_classes
-        defined = StylesheetScanner.new(root: @root, config: @config).defined_classes
-        (defined - used).sort.map { |name| Ghost.new(class_name: name) }
-      end
-
-      def print_summary
-        ghosts = ghost_classes
-        used_count = ViewScanner.new(root: @root, config: @config).used_classes.size
-        defined_count = StylesheetScanner.new(root: @root, config: @config).defined_classes.size
-
-        @output.puts
-        @output.puts "rails-css_unused — Ghost Class Report"
-        @output.puts "=" * 40
-        @output.puts "Project root: #{@root}"
-        @output.puts "Classes in stylesheets: #{defined_count}"
-        @output.puts "Classes referenced in views: #{used_count}"
-        @output.puts "Ghost classes (in CSS, not in views): #{ghosts.size}"
-        @output.puts
-
-        if ghosts.empty?
-          @output.puts "No ghost classes found. Nice and tidy!"
-        else
-          @output.puts "Ghost classes:"
-          ghosts.each { |g| @output.puts "  #{g.class_name}" }
-        end
-
-        @output.puts
-        @output.puts "Note: Dynamic class names and Tailwind utilities compiled at build time"
-        @output.puts "may produce false positives. See README for configuration."
-        @output.puts
-
-        ghosts
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative "spinner"
+
+module Rails
+  module CssUnused
+    # Computes and renders the unused CSS class report.
+    class Report
+      Ghost = Struct.new(:class_name, :source_file, keyword_init: true)
+
+      RESET  = "\e[0m"
+      BOLD   = "\e[1m"
+      RED    = "\e[31m"
+      GREEN  = "\e[32m"
+      YELLOW = "\e[33m"
+      CYAN   = "\e[36m"
+      GRAY   = "\e[90m"
+
+      def initialize(root:, output: $stdout, config: CssUnused.configuration)
+        @root   = Pathname(root)
+        @output = output
+        @config = config
+        @tty    = output.respond_to?(:isatty) && output.isatty
+      end
+
+      # Returns Array<Ghost> of unused classes.
+      def ghost_classes
+        used    = Spinner.run("Scanning views & components") { ViewScanner.new(root: @root, config: @config).used_classes }
+        defined = Spinner.run("Scanning stylesheets")        { StylesheetScanner.new(root: @root, config: @config).defined_classes_with_sources }
+
+        unused_names = defined.map(&:name).to_set - used
+        defined
+          .select { |dc| unused_names.include?(dc.name) }
+          .sort_by(&:name)
+          .map { |dc| Ghost.new(class_name: dc.name, source_file: dc.source_file) }
+      end
+
+      # Prints the full report to @output.
+      # Returns the exit code (0 = clean, 1 = ghosts found and fail_on_unused set).
+      def print_summary
+        puts_color "", nil
+        puts_color "rails-css_unused v#{Rails::CssUnused::VERSION}", BOLD
+
+        # ── Scan with spinners ────────────────────────────────────────────
+        used = Spinner.run("Scanning views & components") do
+          ViewScanner.new(root: @root, config: @config).used_classes
+        end
+
+        defined = Spinner.run("Scanning stylesheets") do
+          StylesheetScanner.new(root: @root, config: @config).defined_classes_with_sources
+        end
+
+        ghosts = Spinner.run("Comparing & computing ghost classes") do
+          unused_names = defined.map(&:name).to_set - used
+          defined
+            .select { |dc| unused_names.include?(dc.name) }
+            .sort_by(&:name)
+            .map { |dc| Ghost.new(class_name: dc.name, source_file: dc.source_file) }
+        end
+
+        # ── Report ────────────────────────────────────────────────────────
+        puts_color "", nil
+        puts_color "Ghost Class Report", BOLD
+        puts_color "=" * 44, GRAY
+        puts_color "Project root              : #{@root}", nil
+        puts_color "Stylesheet classes found  : #{defined.size}", CYAN
+        puts_color "View classes referenced   : #{used.size}", CYAN
+        puts_color "Ghost classes (unused)    : #{ghosts.size}", ghosts.empty? ? GREEN : RED
+        puts_color "", nil
+
+        if ghosts.empty?
+          puts_color "✓ No ghost classes found — stylesheet is clean!", GREEN
+        else
+          puts_color "Ghost classes:", BOLD
+          puts_color "", nil
+
+          ghosts.each do |g|
+            if @config.show_source_files && g.source_file
+              relative = g.source_file.relative_path_from(@root) rescue g.source_file
+              puts_color "  #{g.class_name}", RED
+              puts_color "    → #{relative}", GRAY
+            else
+              puts_color "  • #{g.class_name}", RED
+            end
+          end
+
+          puts_color "", nil
+          puts_color "Tip: Add classes to ignore_classes or ignore_patterns in your initializer", YELLOW
+          puts_color "     if they are used dynamically (JS, server-side conditions, third-party).", YELLOW
+        end
+
+        puts_color "", nil
+        puts_color "Note: Dynamic class names (JS conditions, runtime interpolation) may still", GRAY
+        puts_color "produce false positives. Enable scan_javascript_for_classes to reduce them.", GRAY
+        puts_color "", nil
+
+        (ghosts.any? && @config.fail_on_unused) ? 1 : 0
+      end
+
+      private
+
+      def puts_color(msg, color)
+        if @tty && color
+          @output.puts "#{color}#{msg}#{RESET}"
+        else
+          @output.puts msg
+        end
+      end
+    end
+  end
+end

data/lib/rails/css_unused/spinner.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Rails
+  module CssUnused
+    # A lightweight TTY spinner shown while scanning is in progress.
+    # Automatically disabled when output is not a TTY (CI, pipes, file output).
+    class Spinner
+      FRAMES  = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+      BOLD    = "\e[1m"
+      CYAN    = "\e[36m"
+      GREEN   = "\e[32m"
+      YELLOW  = "\e[33m"
+      RESET   = "\e[0m"
+      CLEAR   = "\r\e[K"   # move to column 0, erase line
+
+      INTERVAL = 0.08  # seconds between frames
+
+      def initialize(output: $stderr)
+        @output  = output
+        @tty     = output.respond_to?(:isatty) && output.isatty
+        @thread  = nil
+        @frame   = 0
+        @label   = ""
+      end
+
+      # Run a block with a spinner, returning the block's return value.
+      # The spinner is suppressed when not on a TTY.
+      #
+      #   result = Spinner.run("Scanning stylesheets") { expensive_work }
+      #
+      def self.run(label, output: $stderr, &block)
+        new(output: output).run(label, &block)
+      end
+
+      def run(label, &block)
+        @label = label
+        start!
+        result = block.call
+        stop!(success: true)
+        result
+      rescue => e
+        stop!(success: false)
+        raise e
+      end
+
+      private
+
+      def start!
+        return unless @tty
+
+        @running = true
+        @thread  = Thread.new do
+          while @running
+            render_frame
+            sleep INTERVAL
+          end
+        end
+      end
+
+      def stop!(success:)
+        return unless @tty
+
+        @running = false
+        @thread&.join
+        @thread = nil
+
+        icon  = success ? "#{GREEN}✔#{RESET}" : "#{YELLOW}✘#{RESET}"
+        @output.print "#{CLEAR}#{icon} #{BOLD}#{@label}#{RESET}\n"
+      end
+
+      def render_frame
+        frame = FRAMES[@frame % FRAMES.size]
+        @frame += 1
+        @output.print "#{CLEAR}#{CYAN}#{frame}#{RESET} #{BOLD}#{@label}…#{RESET}"
+      end
+    end
+  end
+end

data/lib/rails/css_unused/stylesheet_scanner.rb

@@ -1,82 +1,149 @@
-# frozen_string_literal: true
-
-module Rails
-  module CssUnused
-    # Extracts class selectors from CSS/SCSS/Sass files (static parse, no full AST).
-    class StylesheetScanner
-      # .class-name, .foo.bar, div.class — capture class tokens after dots
-      CLASS_SELECTOR_PATTERN = /\.([a-zA-Z_][\w-]*(?:--[\w-]+)?)/
-
-      # Strip comments before matching
-      BLOCK_COMMENT = %r{/\*.*?\*/}m
-      LINE_COMMENT = %r{//[^\n]*}
-
-      def initialize(root:, config: CssUnused.configuration)
-        @root = Pathname(root)
-        @config = config
-      end
-
-      def defined_classes
-        classes = Set.new
-        each_stylesheet_file { |content| classes.merge(extract_from(strip_comments(content))) }
-        classes.subtract(normalized_ignore_list)
-        classes
-      end
-
-      private
-
-      def each_stylesheet_file
-        search_roots = @config.stylesheet_paths + @config.javascript_paths
-        extensions = Configuration::CSS_EXTENSIONS
-
-        search_roots.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)
-
-            yield read_file(path)
-          end
-        end
-      end
-
-      def read_file(path)
-        path.read(encoding: Encoding::UTF_8)
-      rescue ArgumentError
-        path.read
-      end
-
-      def strip_comments(css)
-        css.gsub(BLOCK_COMMENT, "").gsub(LINE_COMMENT, "")
-      end
-
-      def extract_from(css)
-        found = Set.new
-        css.scan(CLASS_SELECTOR_PATTERN) do |match|
-          class_name = match.is_a?(Array) ? match[0] : match
-          next if skip_selector?(class_name, css)
-
-          found << class_name
-        end
-        found
-      end
-
-      def skip_selector?(class_name, _css)
-        return true if pseudo_or_utility_noise?(class_name)
-
-        @config.ignore_selectors_matching.any? { |pattern| class_name.match?(pattern) }
-      end
-
-      def pseudo_or_utility_noise?(name)
-        %w[import media charset namespace].include?(name)
-      end
-
-      def normalized_ignore_list
-        @config.ignore_classes.map(&:to_s)
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    # Scans CSS / SCSS / Sass stylesheets and extracts every defined class selector.
+    #
+    # Key improvements over v0.1:
+    #  - Tracks which FILE each class was defined in (for --show-source-files).
+    #  - Properly strips @charset, @import, @media, @keyframes, @font-face noise.
+    #  - Ignores pseudo-class arguments like :not(.foo) — .foo is counted as used.
+    #  - Handles BEM double-dash and double-underscore selectors.
+    #  - Skips file-extension false positives (.png, .jpg, .css, .js etc.)
+    #  - Skips @-rule word tokens that look like class selectors (.keyframe-name).
+    #  - Applies ignore_classes AND ignore_patterns from configuration.
+    class StylesheetScanner
+      # Match .classname anywhere a class selector can appear.
+      # Deliberately broad — noise is filtered by the skip logic below.
+      CLASS_SELECTOR_PATTERN = /(?<![:\w])\.(-?[a-zA-Z_][a-zA-Z0-9_-]*)/
+
+      BLOCK_COMMENT  = %r{/\*.*?\*/}m
+      LINE_COMMENT   = %r{//[^\n]*}
+      STRING_LITERAL = /(['"])(?:(?!\1).)*\1/   # strip quoted strings first
+
+      # At-rule keywords whose following token looks like a class selector
+      # but is actually metadata: @charset, @import, @namespace, @keyframes, etc.
+      AT_RULE_NOISE = %w[
+        charset import namespace supports keyframes
+        font-face font-feature-values counter-style layer
+        page media document
+      ].freeze
+
+      # File extensions that produce false positives when found after a dot.
+      EXTENSION_NOISE = %w[
+        png jpg jpeg gif svg webp ico bmp tiff
+        css scss sass less
+        js ts jsx tsx mjs cjs
+        rb erb haml slim html htm xml json yaml yml
+        pdf zip gz tar woff woff2 ttf eot
+        map min
+      ].freeze
+
+      # Result struct — class name plus the file it was found in.
+      DefinedClass = Struct.new(:name, :source_file, keyword_init: true)
+
+      def initialize(root:, config: CssUnused.configuration)
+        @root   = Pathname(root)
+        @config = config
+      end
+
+      # Returns a Set of plain class name strings (for diff calculations).
+      def defined_classes
+        scan_all.map(&:name).to_set
+      end
+
+      # Returns Array<DefinedClass> with source file info.
+      def defined_classes_with_sources
+        scan_all
+      end
+
+      private
+
+      def scan_all
+        results = []
+        ignore_set      = @config.ignore_classes.map(&:to_s).to_set
+        ignore_patterns = Array(@config.ignore_patterns)
+
+        each_stylesheet_file do |path, content|
+          extract_from(clean(content), path).each do |name|
+            next if ignore_set.include?(name)
+            next if ignore_patterns.any? { |pat| name.match?(pat) }
+            results << DefinedClass.new(name: name, source_file: path)
+          end
+        end
+
+        # Deduplicate by name, keeping first occurrence.
+        seen = Set.new
+        results.select { |dc| seen.add?(dc.name) }
+      end
+
+      def each_stylesheet_file
+        dirs = (@config.stylesheet_paths + @config.javascript_paths)
+               .map { |p| @root.join(p) }
+               .select(&:directory?)
+
+        dirs.each do |dir|
+          Dir.glob(dir.join("**", "*")).each do |file|
+            path = Pathname(file)
+            next unless path.file?
+            next unless Configuration::CSS_EXTENSIONS.include?(path.extname)
+
+            content = safe_read(path)
+            yield path, content if content
+          end
+        end
+      end
+
+      # Remove comments and string literals so we don't extract class names
+      # from inside @import "file.css" or url("image.png").
+      def clean(css)
+        css
+          .gsub(BLOCK_COMMENT, " ")
+          .gsub(LINE_COMMENT,  " ")
+          .gsub(STRING_LITERAL, " ")
+      end
+
+      def extract_from(css, _path)
+        found = Set.new
+
+        css.scan(CLASS_SELECTOR_PATTERN) do |match|
+          name = match[0]
+          next if skip?(name, Regexp.last_match.pre_match)
+          found << name
+        end
+
+        found
+      end
+
+      def skip?(name, pre_match)
+        # File extension false positives: .png .jpg .css etc.
+        return true if EXTENSION_NOISE.include?(name.downcase)
+
+        # Pure numbers or starting with a digit
+        return true if name.match?(/\A\d/)
+
+        # Single-character tokens are almost always noise
+        return true if name.length == 1
+
+        # At-rule keyword false positives: @keyframes slide-in → .slide-in is OK,
+        # but @charset, @import etc. followed by a dot-prefixed string.
+        preceding_word = pre_match.strip.split(/\s+/).last.to_s.gsub(/\A@/, "")
+        return true if AT_RULE_NOISE.include?(preceding_word.downcase)
+
+        # :not(.foo), :is(.foo), :where(.foo) — .foo is a USED class, not defined here.
+        # We skip it from the defined set; it will be found in views anyway.
+        return true if pre_match.match?(/:(not|is|where|has)\s*\(\s*\z/)
+
+        false
+      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/tasks.rake

@@ -1,12 +1,32 @@
-# frozen_string_literal: true
-
-namespace :css_unused do
-  desc "List CSS classes defined in stylesheets but not referenced in views/components"
-  task report: :environment do
-    require "rails/css_unused"
-    Rails::CssUnused.report
-  end
-
-  desc "Same as report (alias)"
-  task ghosts: :report
-end
+# frozen_string_literal: true
+
+namespace :css_unused do
+  desc "List CSS classes defined in stylesheets but never referenced in views/components"
+  task report: :environment do
+    require "rails/css_unused"
+    exit_code = Rails::CssUnused.report
+    exit(exit_code) if exit_code != 0
+  end
+
+  desc "Alias for css_unused:report"
+  task ghosts: :report
+
+  desc "Exit with code 1 if any ghost classes exist (CI-friendly)"
+  task ci: :environment do
+    require "rails/css_unused"
+    original = Rails::CssUnused.configuration.fail_on_unused
+    Rails::CssUnused.configuration.fail_on_unused = true
+    exit_code = Rails::CssUnused.report
+    Rails::CssUnused.configuration.fail_on_unused = original
+    exit(exit_code) if exit_code != 0
+  end
+
+  desc "Show ghost classes with their source stylesheet file"
+  task report_verbose: :environment do
+    require "rails/css_unused"
+    original = Rails::CssUnused.configuration.show_source_files
+    Rails::CssUnused.configuration.show_source_files = true
+    Rails::CssUnused.report
+    Rails::CssUnused.configuration.show_source_files = original
+  end
+end

data/lib/rails/css_unused/version.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
-module Rails
-  module CssUnused
-    VERSION = "0.1.0"
-  end
-end
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    VERSION = "0.2.1"
+  end
+end