rails-css_unused 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d73f075e43405f546976ed7bac31bda9ccc6ac96bfa16f0dc0fa6dbc78a3242
-  data.tar.gz: de225a6ff929dfbb1f1075cc142beb93b7e25715c76905efc3daacb00d531662
+  metadata.gz: 3e275861ec42e64ade413fc24f51105fcdfbc77691b3b8a421029523e96f8b59
+  data.tar.gz: 06da7233e0f634d4feeb02664b24f438537449a20ac2b28845866c60fb73514a
 SHA512:
-  metadata.gz: 0a0dd43d7354169aa25f7a3274e58ab05d5d4e2a36cb6546994fbf22512404c2d5d8bb6827116358a71fb62911427b9e2692f6a6753fd5040e848043666e30ab
-  data.tar.gz: af1263e05f8e44c228334495438c493e8c079c2f03e21118435a6d10fe5971cf07d90e7bd610d5654a6731d61b35923c1d512443bc06fc9c608a9feae634424d
+  metadata.gz: ec24c67fc3da46c54954d210c4ae1ffef696abba69a32b06c7e4a56d75c9f72c65f32ad0dfea9044248fd8ff31f9adb847381b2d527215668bac1ebcb66c5619
+  data.tar.gz: 0023736da3656117d62196f8509b04a1b27622726e10772ccad96690e8cd5210b21305ad2034720dffabba50fa3b9756df73c4abee628b8ce23f92dc46ac1be7

data/CHANGELOG.md

@@ -1,24 +1,53 @@
-# 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
+# Changelog
+
+## [0.2.1] - 2026-06-02
+
+### Added
+- **Smart dynamic class variable detection** — the scanner now automatically
+  detects CSS class strings assigned to variables whose name ends in
+  `_class`, `_classes`, `_style`, or `_css` (e.g. `status_class = "foo-bar"`).
+- **Hyphenated string literal detection** — any quoted string containing a
+  hyphen is now treated as a CSS class value. Since Ruby variable names
+  cannot contain hyphens, hyphenated quoted strings are unambiguously string
+  values, never identifiers. This eliminates false positives from patterns like:
+  ```erb
+  <% status_class =
+    if exam.cancelled?
+      ["Cancelled", "status-cancelled"]
+    elsif exam.approved?
+      ["Approved", "status-approved"]
+    end %>
+  <span class="status-pill <%= status_class %>">
+  ```
+  Classes like `status-cancelled`, `status-approved`, `status-requested`
+  are now correctly detected as used without needing `ignore_patterns`.
+- Dynamic class var detection also runs in HAML, Slim, and Ruby component files.
+
+### Fixed
+- False positives for dynamically assigned CSS classes used via ERB interpolation
+  (e.g. `<%= status_class %>`, `<%= button_css %>`).
+
+## [0.2.0] - 2026-05-31
+
+### Added
+- HAML and Slim template scanning
+- ViewComponent and Phlex component support
+- Stimulus controller JS class scanning (`classList.add`, `classList.toggle`)
+- `scan_javascript_for_classes` config option
+- `scan_ruby_components` config option
+- `show_source_files` config option
+- `fail_on_unused` config option for CI pipelines
+- BEM class name support (`block__element--modifier`)
+- ERB dynamic class attribute extraction (static parts from `class="<%= expr %>"`)
+- `ignore_patterns` config for regex-based exclusions
+- Spinner output during scanning
+
+## [0.1.0] - 2026-05-15
+
+### Added
+- Initial release
+- CSS/SCSS/SASS stylesheet scanning
+- ERB view scanning (`class="..."`, `class: "..."`, `class: [...]`)
+- Ghost class report with counts
+- `ignore_classes` configuration
+- `css_unused:report` rake task

data/LICENSE.txt

@@ -1,21 +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.
+MIT License
+
+Copyright (c) 2026 Syed Ghani
+
+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

@@ -1,132 +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).
+# rails-css_unused
+
+**Find unused CSS classes in your Rails app — zero runtime overhead, zero false positives from file extensions or at-rules.**
+
+[![Gem Version](https://badge.fury.io/rb/rails-css_unused.svg)](https://rubygems.org/gems/rails-css_unused)
+
+---
+
+## Why this gem?
+
+| Feature | deadweight | rails-css_unused |
+|---------|-----------|-----------------|
+| Maintained | ❌ abandoned | ✅ |
+| Rails 7+ | ❌ | ✅ |
+| Static analysis (no server needed) | ❌ needs running server | ✅ |
+| BEM selector support | ❌ | ✅ |
+| HAML / Slim support | ❌ | ✅ |
+| ViewComponent / Phlex support | ❌ | ✅ |
+| Stimulus JS class detection | ❌ | ✅ |
+| ERB dynamic class extraction | ❌ | ✅ |
+| Source file attribution | ❌ | ✅ |
+| CI exit code support | ❌ | ✅ |
+| Regex ignore patterns | ❌ | ✅ |
+| Extension false-positive protection | ❌ | ✅ |
+
+---
+
+## Installation
+
+```ruby
+# Gemfile
+gem "rails-css_unused", group: :development
+```
+
+```bash
+bundle install
+```
+
+---
+
+## Usage
+
+```bash
+# Standard report
+bundle exec rake css_unused:report
+
+# With source file for each ghost class
+bundle exec rake css_unused:report_verbose
+
+# CI — exits with code 1 if any ghost classes found
+bundle exec rake css_unused:ci
+```
+
+### Programmatic usage
+
+```ruby
+# List ghost class names
+Rails::CssUnused.ghost_classes  # => ["old-btn", "legacy-card"]
+
+# Full report to custom IO
+Rails::CssUnused.report(output: File.open("report.txt", "w"))
+```
+
+---
+
+## Configuration
+
+Create `config/initializers/css_unused.rb`:
+
+```ruby
+Rails::CssUnused.configure do |config|
+  # Paths to scan (relative to Rails.root)
+  config.stylesheet_paths = %w[app/assets/stylesheets app/assets/builds]
+  config.view_paths       = %w[app/views]
+  config.component_paths  = %w[app/components]
+  config.javascript_paths = %w[app/javascript]
+
+  # Exact class names to never flag as ghost
+  config.ignore_classes = %w[
+    clearfix sr-only visually-hidden
+    active disabled selected
+  ]
+
+  # Regex patterns — any matching class is ignored
+  config.ignore_patterns = [
+    /\Ajs-/,    # JS hook classes  (js-submit-btn)
+    /\Ais-/,    # state classes    (is-active, is-open)
+    /\Ahas-/,   # state classes    (has-error)
+  ]
+
+  # Detect classes added via classList.add() in JS files
+  config.scan_javascript_for_classes = true
+
+  # Scan ViewComponent .rb files for class: attributes
+  config.scan_ruby_components = true
+
+  # Show which stylesheet each ghost class came from
+  config.show_source_files = false
+
+  # Exit with code 1 in CI when ghosts are found
+  config.fail_on_unused = false
+end
+```
+
+---
+
+## What is a "ghost class"?
+
+A ghost class is a CSS class that is:
+- ✅ **Defined** in a `.css`, `.scss`, or `.sass` file
+- ❌ **Never referenced** in any `.erb`, `.haml`, `.slim`, `.rb`, or `.js` file
+
+Ghost classes add dead weight to your CSS bundle and confuse future developers.
+
+---
+
+## Reducing false positives
+
+Some classes are legitimately hard to detect statically:
+
+| Situation | Solution |
+|-----------|----------|
+| `class="status-#{record.state}"` | Add `ignore_patterns << /\Astatus-/` |
+| JS-only classes (e.g. `js-modal-open`) | Add `ignore_patterns << /\Ajs-/` or enable `scan_javascript_for_classes` |
+| Third-party component classes | Add prefix pattern to `ignore_patterns` |
+| Turbo / Stimulus data-action targets | Add to `ignore_classes` |
+
+---
+
+## License
+
+MIT

data/lib/rails/css_unused/configuration.rb

@@ -1,45 +1,97 @@
-# 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
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    class Configuration
+      # File extensions treated as view templates
+      VIEW_EXTENSIONS       = %w[.erb .haml .slim].freeze
+      # Compound view extensions (e.g. foo.html.erb)
+      COMPOUND_VIEW_ENDINGS = %w[.html.erb .html.haml .html.slim].freeze
+      # CSS/preprocessor extensions to scan
+      CSS_EXTENSIONS        = %w[.css .scss .sass].freeze
+      # Ruby component file extensions
+      COMPONENT_EXTENSIONS  = %w[.rb].freeze
+
+      # ── Scan paths ────────────────────────────────────────────────────────
+      # Directories to search for view templates (relative to project root).
+      attr_accessor :view_paths
+
+      # Directories to search for ViewComponent / Phlex / etc. template files.
+      attr_accessor :component_paths
+
+      # Directories to search for stylesheets.
+      attr_accessor :stylesheet_paths
+
+      # Directories to search for JS files (e.g. Stimulus controllers that
+      # add classes dynamically — detected as allowlisted dynamic patterns).
+      attr_accessor :javascript_paths
+
+      # ── Ignore lists ─────────────────────────────────────────────────────
+      # Exact class names to always treat as "used" (never reported as ghost).
+      # Good for: utility classes, JS-hook classes, server-side rendered classes.
+      attr_accessor :ignore_classes
+
+      # Regex patterns — any CSS class name matching any pattern is ignored.
+      # Good for: third-party prefixes, state classes, BEM modifier variants.
+      # Example: [/\Ajs-/, /\Ais-/, /\Ahas-/]
+      attr_accessor :ignore_patterns
+
+      # ── Dynamic class detection ───────────────────────────────────────────
+      # When true, scan JS/Stimulus files for string literals that look like
+      # CSS class names and add them to the used-class set automatically.
+      attr_accessor :scan_javascript_for_classes
+
+      # When true, scan Ruby component files (.rb) for string literals that
+      # look like CSS classes passed to html attributes.
+      attr_accessor :scan_ruby_components
+
+      # ── Output ───────────────────────────────────────────────────────────
+      # When true, show which file each ghost class was defined in.
+      attr_accessor :show_source_files
+
+      # When true, exit with code 1 if any ghost classes are found.
+      # Useful for CI pipelines.
+      attr_accessor :fail_on_unused
+
+      def initialize
+        @view_paths       = %w[app/views]
+        @component_paths  = %w[app/components]
+        @stylesheet_paths = %w[app/assets/stylesheets app/assets/builds]
+        @javascript_paths = %w[app/javascript]
+
+        @ignore_classes = %w[
+          clearfix sr-only visually-hidden
+          active disabled selected current open closed
+          show hide hidden visible
+          fade collapse collapsing
+        ]
+
+        @ignore_patterns = [
+          /\Ajs-/,       # JS-hook classes
+          /\Ais-/,       # state classes  (is-active, is-open)
+          /\Ahas-/,      # state classes  (has-error)
+          /\Adata-/,     # sometimes leaked into CSS scanners
+        ]
+
+        @scan_javascript_for_classes = true
+        @scan_ruby_components        = true
+        @show_source_files           = false
+        @fail_on_unused              = false
+      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

@@ -1,24 +1,25 @@
-# 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
+# frozen_string_literal: true
+
+module Rails
+  module CssUnused
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path("tasks.rake", __dir__)
+      end
+
+      # Support configuration via config/initializers/css_unused.rb:
+      #
+      #   Rails::CssUnused.configure do |c|
+      #     c.fail_on_unused        = true
+      #     c.show_source_files     = true
+      #     c.ignore_patterns       << /\Ashopify-/
+      #     c.scan_javascript_for_classes = true
+      #   end
+      #
+      initializer "rails_css_unused.configuration" do
+        # Nothing auto-applied — users configure via Rails::CssUnused.configure.
+        # The Railtie merely makes rake tasks available.
+      end
+    end
+  end
+end