rails-css_unused 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d73f075e43405f546976ed7bac31bda9ccc6ac96bfa16f0dc0fa6dbc78a3242
-  data.tar.gz: de225a6ff929dfbb1f1075cc142beb93b7e25715c76905efc3daacb00d531662
+  metadata.gz: 6be69a5f6aa27dedb1aef9797167bf8b8abed066632fa8fee01fe7fefa54554c
+  data.tar.gz: c808dfa0ed3b70ad3a03ec158af1ef5d00a7bcf97ff899b6f4613853955c67fd
 SHA512:
-  metadata.gz: 0a0dd43d7354169aa25f7a3274e58ab05d5d4e2a36cb6546994fbf22512404c2d5d8bb6827116358a71fb62911427b9e2692f6a6753fd5040e848043666e30ab
-  data.tar.gz: af1263e05f8e44c228334495438c493e8c079c2f03e21118435a6d10fe5971cf07d90e7bd610d5654a6731d61b35923c1d512443bc06fc9c608a9feae634424d
+  metadata.gz: 62d8dff321fb2dddf72d618747b2e22511a438864b0372067c9c222442f1a39f30513a8922d014a663c4dde0955ca44614d3b9506476df78d41ef7a517ed88cb
+  data.tar.gz: 3e7e72d6cb22f7a6a1138162771cb3906e0b9a1399070131ab660b7a43286f4957faa15dd6d51b14a3981f36779264aa6da38a9ab04cbec1b8c889c189f30db8

data/CHANGELOG.md

@@ -1,24 +1,30 @@
-# 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.0] - 2026-06-02
+
+### 🔧 Fixed
+- **Extension noise eliminated** — `.png`, `.css`, `.jpg`, `.js` etc. no longer appear as ghost classes
+- **At-rule noise eliminated** — `@charset`, `@import`, `@keyframes` tokens no longer pollute the class list
+- **`:not()` false positives fixed** — `.foo` inside `:not(.foo)` is no longer treated as a new definition
+- **Double-scanning removed** — `ViewScanner` and `StylesheetScanner` were each instantiated twice in `print_summary`, wasting time and producing wrong counts
+
+### ✨ Added
+- **Source file attribution** — `show_source_files: true` shows which stylesheet each ghost comes from
+- **CI mode** — `fail_on_unused: true` + `rake css_unused:ci` exits with code 1 on any ghost
+- **`rake css_unused:report_verbose`** — shows ghost classes with source file inline
+- **HAML & Slim support** — proper extraction of `.foo.bar` shorthand selectors
+- **Slim template support** — `div.foo` class shorthand
+- **Ruby component support** — scans ViewComponent `.rb` files for `class:` attributes
+- **Stimulus / JS support** — `classList.add("foo")` calls detected as used classes
+- **ERB dynamic class extraction** — `class="<%= cond ? 'a' : 'b' %>"` — static string parts extracted
+- **`ignore_patterns`** — regex-based ignore list (e.g. `/\Ajs-/`, `/\Ais-/`)
+- **`scan_javascript_for_classes`** — opt-in JS scanning for dynamically applied classes
+- **`scan_ruby_components`** — opt-in scanning of `.rb` component files
+- **Colour terminal output** — red/green/grey ANSI when outputting to a TTY
+- **BEM double-underscore selectors** — `block__element--modifier` handled correctly
+
+### 🗑️ Removed
+- Confusing `stylesheet_scanner.rb` noise filter that used a hardcoded `%w[import media charset...]` list (replaced with proper context-aware skip logic)
+
+## [0.1.0] - 2026-05-01
+- Initial release

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 sghani001
+
+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