rails-css_unused 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d73f075e43405f546976ed7bac31bda9ccc6ac96bfa16f0dc0fa6dbc78a3242
+  data.tar.gz: de225a6ff929dfbb1f1075cc142beb93b7e25715c76905efc3daacb00d531662
+SHA512:
+  metadata.gz: 0a0dd43d7354169aa25f7a3274e58ab05d5d4e2a36cb6546994fbf22512404c2d5d8bb6827116358a71fb62911427b9e2692f6a6753fd5040e848043666e30ab
+  data.tar.gz: af1263e05f8e44c228334495438c493e8c079c2f03e21118435a6d10fe5971cf07d90e7bd610d5654a6731d61b35923c1d512443bc06fc9c608a9feae634424d

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-01
+
+### Added
+
+- `css_unused:report` and `css_unused:ghosts` Rake tasks (via Railtie)
+- View scanner for `app/views` and `app/components` (ERB, HAML, `class:` helpers)
+- Stylesheet scanner for CSS/SCSS/Sass under assets and `app/javascript`
+- `Rails::CssUnused.report` and `Rails::CssUnused.ghost_classes` APIs
+- `Rails::CssUnused.configure` for paths and ignored classes
+
+### Known limitations
+
+- Dynamic classes in ERB may not be detected
+- Tailwind / build-time utilities may report false positives
+- Classes added only via JavaScript are not detected
+
+[0.1.0]: https://github.com/sghani001/rails-css_unused/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,132 @@
+# rails-css_unused
+
+[![Gem Version](https://img.shields.io/gem/v/rails-css_unused)](https://rubygems.org/gems/rails-css_unused)
+[![GitHub](https://img.shields.io/github/stars/sghani001/rails-css_unused?style=social)](https://github.com/sghani001/rails-css_unused)
+
+Find **ghost CSS classes** in your Rails app: selectors that exist in your stylesheets but never show up in views or ViewComponents.
+
+Pure static analysis — no browser, no headless Chrome. Built for the usual Rails paths (`app/views`, `app/components`, `app/assets/stylesheets`).
+
+## Requirements
+
+- Ruby **>= 3.1**
+- Rails **>= 7.0** (via `railties`)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "rails-css_unused", group: :development
+```
+
+```bash
+bundle install
+```
+
+Or install the gem directly (after it is published on RubyGems):
+
+```bash
+gem install rails-css_unused
+```
+
+During development of this gem itself, use a path install:
+
+```ruby
+gem "rails-css_unused", path: "../rails-css_unused", group: :development
+```
+
+## Usage
+
+```bash
+bin/rails css_unused:report
+# or
+bin/rails css_unused:ghosts
+```
+
+Example output:
+
+```
+rails-css_unused — Ghost Class Report
+========================================
+Project root: /path/to/myapp
+Classes in stylesheets: 142
+Classes referenced in views: 118
+Ghost classes (in CSS, not in views): 24
+
+Ghost classes:
+  legacy-banner
+  orphan-widget
+  ...
+```
+
+## What it scans
+
+| Source | Paths (default) |
+|--------|-----------------|
+| Views | `app/views` — `.html.erb`, `.html.haml`, `.haml`, `.erb`, `.slim` |
+| Components | `app/components` — same extensions |
+| Styles | `app/assets/stylesheets`, `app/assets/builds` — `.css`, `.scss`, `.sass` |
+| JS CSS | `app/javascript` — same stylesheet extensions |
+
+### Class detection in templates
+
+- `class="foo bar"`
+- `class: "foo"`, `class: 'foo'`
+- `class: %w[foo bar]`, `class: ["foo", "bar"]`
+- `tag.div ..., class: "foo"`
+- Basic HAML `.class-name` segments
+
+## Configuration
+
+```ruby
+# config/initializers/rails_css_unused.rb
+Rails::CssUnused.configure do |config|
+  config.ignore_classes += %w[active hidden]
+  config.stylesheet_paths << "vendor/assets/stylesheets"
+  config.view_paths << "app/views/admin"
+end
+```
+
+Optional `config/application.rb` hook:
+
+```ruby
+config.rails_css_unused = ActiveSupport::OrderedOptions.new
+config.rails_css_unused.ignore_classes = %w[sr-only]
+```
+
+## Limitations
+
+Static analysis cannot see everything:
+
+- **Dynamic classes** — `class="<%= dynamic %>"` may be missed or only partially detected.
+- **Tailwind / utility frameworks** — utilities are often generated at build time; many “ghost” hits are false positives unless you scan compiled `app/assets/builds` and tune `ignore_classes`.
+- **JavaScript-added classes** — Stimulus, React, or `element.classList.add` are not scanned.
+- **@extend / mixins** — SCSS may define classes only used inside other rules; review before deleting.
+
+Treat the report as a **triage list**, not an automatic delete command.
+
+## Programmatic API
+
+```ruby
+Rails::CssUnused.ghost_classes
+# => ["orphan-widget", "legacy-banner", ...]
+
+Rails::CssUnused.report
+```
+
+## Development
+
+```bash
+bundle install
+ruby -Ilib -S rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/sghani001/rails-css_unused).
+
+Maintainers: see [PUBLISHING.md](PUBLISHING.md) for the release checklist and RubyGems publish steps.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/rails/css_unused/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    class Configuration
+      VIEW_EXTENSIONS = %w[.html.erb .html.haml .haml .erb .slim .jbuilder].freeze
+      COMPONENT_EXTENSIONS = %w[.html.erb .html.haml .haml .erb .slim].freeze
+      CSS_EXTENSIONS = %w[.css .scss .sass].freeze
+
+      attr_accessor :view_paths,
+                    :component_paths,
+                    :stylesheet_paths,
+                    :javascript_paths,
+                    :ignore_classes,
+                    :ignore_selectors_matching
+
+      def initialize
+        @view_paths = ["app/views"]
+        @component_paths = ["app/components"]
+        @stylesheet_paths = ["app/assets/stylesheets", "app/assets/builds"]
+        @javascript_paths = ["app/javascript"]
+        @ignore_classes = %w[
+          clearfix
+          sr-only
+          visually-hidden
+        ]
+        @ignore_selectors_matching = []
+      end
+    end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = nil
+      end
+    end
+  end
+end

data/lib/rails/css_unused/railtie.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path("tasks.rake", __dir__)
+      end
+
+      initializer "rails_css_unused.configuration" do
+        if Rails.application.config.respond_to?(:rails_css_unused)
+          cfg = Rails.application.config.rails_css_unused
+          CssUnused.configure do |c|
+            c.view_paths = cfg.view_paths if cfg.respond_to?(:view_paths) && cfg.view_paths
+            c.component_paths = cfg.component_paths if cfg.respond_to?(:component_paths) && cfg.component_paths
+            c.stylesheet_paths = cfg.stylesheet_paths if cfg.respond_to?(:stylesheet_paths) && cfg.stylesheet_paths
+            c.javascript_paths = cfg.javascript_paths if cfg.respond_to?(:javascript_paths) && cfg.javascript_paths
+            c.ignore_classes = cfg.ignore_classes if cfg.respond_to?(:ignore_classes) && cfg.ignore_classes
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/css_unused/report.rb

@@ -0,0 +1,50 @@
+# 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

data/lib/rails/css_unused/stylesheet_scanner.rb

@@ -0,0 +1,82 @@
+# 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

data/lib/rails/css_unused/tasks.rake

@@ -0,0 +1,12 @@
+# 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

data/lib/rails/css_unused/version.rb

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

data/lib/rails/css_unused/view_scanner.rb

@@ -0,0 +1,117 @@
+# 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

data/lib/rails/css_unused.rb

@@ -0,0 +1,36 @@
+# 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)

data/lib/rails-css_unused.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "rails/css_unused"

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: rails-css_unused
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- sghani001
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
+email:
+- sghani001@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rails-css_unused.rb
+- lib/rails/css_unused.rb
+- lib/rails/css_unused/configuration.rb
+- lib/rails/css_unused/railtie.rb
+- lib/rails/css_unused/report.rb
+- lib/rails/css_unused/stylesheet_scanner.rb
+- lib/rails/css_unused/tasks.rake
+- lib/rails/css_unused/version.rb
+- lib/rails/css_unused/view_scanner.rb
+homepage: https://github.com/sghani001/rails-css_unused
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/sghani001/rails-css_unused
+  source_code_uri: https://github.com/sghani001/rails-css_unused
+  changelog_uri: https://github.com/sghani001/rails-css_unused/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.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: Find unused CSS classes in Rails apps via static analysis
+test_files: []