rubocop-tailwindcss 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 177ea7a79bac1d1fd3f43b13073bcbe7f61ec47939ead3205c4b0529ba7c4bad
-  data.tar.gz: '04085a323580fe32071adb1d798d7c3c2f8dda8b1f2b7c2154ca7e0c177a3e80'
+  metadata.gz: 79100a6f1cd6574dbd77a45b7534cf59a0b5f0402b472530f30f5a2d0c288727
+  data.tar.gz: db1a933d7774841e731dfb7824926356cdd9bd6f4790131c445dd47a917675b3
 SHA512:
-  metadata.gz: 976d160a344bb567d69cace41aef8e05c70630e0f8b29f36d91577070ccba4b771e590ea8cd2f1515863694b819be248da4c20f0e8bc58c67f3c5e53adbf5f02
-  data.tar.gz: d4c002fa3b1060adc73bc8789ef6ecc6cc0ca4aacc5df5135dbc8ea30ed17797ee271a489f13236f551edcb2cc6073c8ea420c734032881535266de532a06d20
+  metadata.gz: 5b240e6a2cf95a112e8f5d43f3e675e565dc19f2222f75bc688f56ea53c0abf6ef334cef0d4d06bb0001617c0fa66912cb999d5b8066f8cb3eb8bb992568c620
+  data.tar.gz: d100558922d06fe2bf88419b3e3a5605c374f7e01202b2d61403999b85b1d87ca33a472964c2f90105ce6de7f01fdb56e871e7f1a821643af07d8003338b0798

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 am1006
+
+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,13 +1,104 @@
 # rubocop-tailwindcss
 
-RuboCop cops that keep Tailwind CSS classes in the official order in Ruby
-code - Phlex components and any Ruby that carries `class:` strings.
+A RuboCop cop that keeps Tailwind CSS classes in the official sort order -
+the same order [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
+produces - wherever Ruby carries them: Phlex components, tag helpers, any
+`class:` string keyword.
 
-**Under development.** This release reserves the name; the first working
-release is being built at
-[am1006/tailwindcss-sorter](https://github.com/am1006/tailwindcss-sorter).
+```ruby
+# bad
+div(class: "px-4 bg-blue-500 text-white rounded py-2")
+cn("px-4 flex", active && "bg-blue-500 rounded")
 
-The plan: the cop finds class strings via the Ruby AST (no regex), batches
-them through the `tailwindcss-sorter` npm CLI - a pinned, theme-aware order
-oracle over Tailwind's own design system - and autocorrects. One Gemfile line;
-no package.json, no node_modules in your Rails app.
+# good (rubocop -a fixes it)
+div(class: "rounded bg-blue-500 px-4 py-2 text-white")
+cn("flex px-4", active && "rounded bg-blue-500")
+```
+
+**No node. No subprocesses. No npx.** The official order is computed by
+Tailwind's own design system - a JavaScript library - which this gem ships as
+a single vendored bundle and evaluates inside an embedded JS engine
+([quickjs](https://rubygems.org/gems/quickjs)), warm for the life of the
+process. Cold start is ~30 ms; each sort is sub-millisecond. Your Rails app
+needs no package.json, no node_modules, no JavaScript toolchain.
+
+## Installation
+
+```ruby
+# Gemfile
+group :development do
+  gem "rubocop-tailwindcss", require: false
+end
+```
+
+```yaml
+# .rubocop.yml
+plugins:
+  - rubocop-tailwindcss
+```
+
+## Usage
+
+- **Fix on command:** `rubocop -a --only Tailwindcss/ClassOrder`
+- **CI:** the cop runs inside your normal `rubocop` invocation
+- **Editors:** ruby-lsp surfaces the offense as a diagnostic with a quick fix,
+  and applies it on format-on-save where safe autocorrection is enabled
+
+## Configuration
+
+```yaml
+Tailwindcss/ClassOrder:
+  # Your Tailwind entry CSS - theme-aware sorting reads @custom-variant,
+  # @theme and friends from here. The default matches tailwindcss-rails.
+  # Set to ~ to sort against Tailwind's default theme instead.
+  # A configured path that does not exist raises rather than sorting wrong.
+  Stylesheet: app/assets/tailwind/application.css
+
+  # Keyword arguments treated as class carriers.
+  Attributes:
+    - class
+    - classes
+
+  # Class-merging functions: every plain string literal inside these calls is
+  # sorted - positional arguments, hash values at any depth (cva variants),
+  # array elements, and the branches of && / || / ternaries.
+  Functions:
+    - cn
+    - cva
+
+  # The embedded JS engine: quickjs (default, ~2 MB, compiles anywhere) or
+  # mini_racer (V8 - add the gem to your Gemfile yourself).
+  Engine: quickjs
+
+  Include:
+    - app/views/**/*.rb
+    - app/components/**/*.rb
+```
+
+## What it deliberately leaves alone
+
+- **Interpolated strings** (`"px-4 #{state}"`) - the sorter cannot know what
+  interpolation produces.
+- **Strings with escape sequences** - source and value diverge; correcting
+  them safely is not worth the machinery for class strings.
+- **`%w[]` arrays** - not covered yet.
+
+One edge to know, inherited deliberately from prettier-plugin-tailwindcss: a
+single literal carrying *conflicting* utilities inside a merge function -
+`cn("p-4 p-2")` - can change its tailwind-merge result when reordered,
+because tailwind-merge is last-wins within a string. The official plugin
+sorts these anyway, and so does this cop: a literal with an internal conflict
+is already a bug, and sorting merely stops it hiding.
+
+## How the order stays honest
+
+The vendored bundle is rebuilt per Tailwind release in
+[the parent repo's factory](https://github.com/am1006/tailwindcss-sorter) and
+proven against the official prettier plugin over a real-world corpus before it
+ships. On boot the sorter runs a self-check (sort a known string, raise loudly
+if it comes back unsorted) - a design system that loads but does not sort
+would otherwise pass every file as clean.
+
+## License
+
+MIT

data/config/default.yml

@@ -0,0 +1,17 @@
+Tailwindcss/ClassOrder:
+  Description: "Sort Tailwind CSS classes in the official order."
+  Enabled: true
+  Safe: true
+  SafeAutoCorrect: true
+  VersionAdded: "0.1"
+  Stylesheet: app/assets/tailwind/application.css
+  Engine: quickjs
+  Attributes:
+    - class
+    - classes
+  Functions:
+    - cn
+    - cva
+  Include:
+    - app/views/**/*.rb
+    - app/components/**/*.rb

data/lib/rubocop/cop/tailwindcss/class_order.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Tailwindcss
+      # Keeps Tailwind CSS classes in the official sort order - the same order
+      # prettier-plugin-tailwindcss produces - wherever Ruby carries them:
+      # `class:` / `classes:` string keywords (Phlex components, tag helpers)
+      # and the string literals inside class-merging functions like `cn` and
+      # `cva`.
+      #
+      # @example
+      #   # bad
+      #   div(class: "px-4 bg-blue-500 flex")
+      #   cn("px-4 flex", active && "bg-muted rounded")
+      #
+      #   # good
+      #   div(class: "flex bg-blue-500 px-4")
+      #   cn("flex px-4", active && "rounded bg-muted")
+      class ClassOrder < Base
+        extend AutoCorrector
+
+        MSG = "Sort Tailwind CSS classes in the official order"
+
+        def on_pair(node)
+          if target_attribute?(node) && sortable?(node.value)
+            check node.value
+          end
+        end
+
+        def on_send(node)
+          if class_function?(node)
+            node.arguments.each { |argument| sort_within argument }
+          end
+        end
+
+        private
+          def target_attribute?(node)
+            node.key.sym_type? && attributes.include?(node.key.value.to_s)
+          end
+
+          def class_function?(node)
+            functions.include?(node.method_name.to_s)
+          end
+
+          # Inside a class function, every plain string literal is a class
+          # string - prettier's contract, followed here: positional arguments,
+          # hash values at any depth, array elements, and the branches of
+          # conditionals. Dynamic nodes (variables, calls, interpolation) stay
+          # untouched, and `class:` pairs stay with on_pair so nothing is
+          # flagged twice.
+          def sort_within(node)
+            case node.type
+            when :str
+              check node if sortable?(node)
+            when :hash, :kwargs, :array, :and, :or, :begin
+              node.children.each { |child| sort_within child if child.is_a?(Parser::AST::Node) }
+            when :pair
+              sort_within node.value unless target_attribute?(node)
+            when :if
+              node.branches.compact.each { |branch| sort_within branch }
+            end
+          end
+
+          # Plain quoted string literals carrying at least two classes.
+          # Interpolation is invisible to the sorter, and escape sequences make
+          # source and value diverge - both are left alone rather than
+          # corrected unsafely.
+          def sortable?(node)
+            node.str_type? && node.value.match?(/\S\s+\S/) && plain_literal?(node)
+          end
+
+          def plain_literal?(node)
+            node.source == %("#{node.value}") || node.source == %('#{node.value}')
+          end
+
+          def check(node)
+            sorted = sorter.sort(node.value)
+            if sorted != node.value
+              add_offense(node) do |corrector|
+                corrector.replace content_range(node), sorted
+              end
+            end
+          end
+
+          def content_range(node)
+            node.source_range.adjust(begin_pos: 1, end_pos: -1)
+          end
+
+          def attributes
+            cop_config.fetch("Attributes", %w[ class classes ])
+          end
+
+          def functions
+            cop_config.fetch("Functions", %w[ cn cva ])
+          end
+
+          def sorter
+            RuboCop::Tailwindcss::Sorter.for stylesheet: stylesheet, engine: cop_config.fetch("Engine", "quickjs")
+          end
+
+          # A configured stylesheet that does not exist would silently sort
+          # with the default theme - wrong for custom variants - so it raises
+          # instead. Set Stylesheet to ~ to sort against the default theme.
+          def stylesheet
+            if path = cop_config["Stylesheet"]
+              unless File.exist?(path)
+                raise RuboCop::Tailwindcss::Sorter::Error,
+                  "stylesheet not found at #{path.inspect} - point Tailwindcss/ClassOrder's " \
+                  "Stylesheet at your Tailwind entry CSS, or set it to ~ for the default theme"
+              end
+              path
+            end
+          end
+      end
+    end
+  end
+end

data/lib/rubocop/tailwindcss/plugin.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "lint_roller"
+
+module RuboCop
+  module Tailwindcss
+    class Plugin < LintRoller::Plugin
+      def about
+        LintRoller::About.new(
+          name: "rubocop-tailwindcss",
+          version: VERSION,
+          homepage: "https://github.com/am1006/tailwindcss-sorter",
+          description: "Sort Tailwind CSS classes in Ruby code in the official order."
+        )
+      end
+
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: Pathname.new(__dir__).join("../../../config/default.yml")
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/tailwindcss/sorter.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Tailwindcss
+    # The order oracle: Tailwind's design system, bundled into a single JS file
+    # and evaluated inside an embedded engine - warm for the life of the
+    # process, no node, no subprocesses. Sorting asks the same
+    # design.getClassOrder that prettier-plugin-tailwindcss asks; the vendored
+    # bundle is proven against the official plugin by this repo's factory.
+    #
+    # Note: the engines' eval APIs only ever receive this gem's own vendored
+    # bundle and JSON-encoded class strings - no untrusted code is evaluated.
+    class Sorter
+      class Error < StandardError; end
+
+      # The Tailwind version the vendored bundle must carry - the one number
+      # this gem's entire behavior derives from. The factory stamps the bundle
+      # at build time and the suite asserts agreement, so bumping either side
+      # alone turns the tests red.
+      TAILWIND_VERSION = "4.3.1"
+
+      BUNDLE_PATH = File.expand_path("../../../vendor/tw-bundle.js", __dir__)
+      DEFAULT_CSS = %(@import "tailwindcss";)
+
+      class << self
+        # One warm oracle per (process, stylesheet, engine). The PID in the key
+        # makes forked rubocop workers each boot their own engine lazily - an
+        # embedded VM must never be shared across a fork.
+        def for(stylesheet:, engine:)
+          key = [ Process.pid, stylesheet, engine ]
+          if @key != key
+            @key = key
+            @instance = new(stylesheet: stylesheet, engine: engine)
+          end
+          @instance
+        end
+      end
+
+      def initialize(stylesheet: nil, engine: "quickjs")
+        @stylesheet = stylesheet
+        @engine = build_engine(engine)
+        boot
+      end
+
+      def sort(class_string)
+        @engine.run("__twSort(#{class_string.to_json})")
+      end
+
+      def tailwind_version
+        @engine.run("__twMeta.tailwind")
+      end
+
+      def entry_sha
+        @engine.run("__twMeta.entrySha")
+      end
+
+      private
+        def build_engine(name)
+          case name.to_s
+          when "quickjs" then QuickjsEngine.new
+          when "mini_racer" then MiniRacerEngine.new
+          else raise Error, %(unknown engine #{name.inspect} - use "quickjs" or "mini_racer")
+          end
+        end
+
+        def boot
+          @engine.run(File.read(BUNDLE_PATH))
+          @engine.run("__twInit(#{user_css.to_json})")
+          @engine.drain
+          assert_loaded
+          assert_sorting
+        end
+
+        def user_css
+          if @stylesheet
+            inline_relative_imports File.read(@stylesheet), File.dirname(@stylesheet)
+          else
+            DEFAULT_CSS
+          end
+        end
+
+        # The design system receives one flat CSS string: Ruby owns the
+        # filesystem, so relative imports are inlined here and only
+        # `@import "tailwindcss"` remains for the bundle's embedded files.
+        def inline_relative_imports(css, dir)
+          css.gsub(%r{@import\s+"(\./[^"]+)"\s*;}) do
+            path = File.expand_path(Regexp.last_match(1), dir)
+            inline_relative_imports File.read(path), File.dirname(path)
+          end
+        end
+
+        def assert_loaded
+          if error = @engine.run("__tw.error")
+            raise Error, "Tailwind design system failed to load: #{error}"
+          end
+          unless @engine.run("__tw.ready")
+            raise Error, "Tailwind design system never became ready - promise jobs stalled in the JS engine"
+          end
+        end
+
+        # A design system that loads but does not sort would pass every file as
+        # clean - prove the order before trusting anything it says.
+        def assert_sorting
+          unless sort("px-4 flex") == "flex px-4"
+            raise Error, "sorter self-check failed - the design system is not ordering classes"
+          end
+        end
+
+      # Engine adapters: same bundle, same calls. QuickJS leaves promise jobs
+      # to the embedder (drain pumps them); V8 drains its microtask queue
+      # itself at the end of every evaluation.
+      class QuickjsEngine
+        def initialize
+          require "quickjs"
+          @vm = Quickjs::VM.new(memory_limit: 256 * 1024 * 1024, timeout_msec: 30_000)
+        end
+
+        def run(code)
+          @vm.eval_code(code)
+        end
+
+        def drain
+          @vm.drain_jobs!
+        end
+      end
+
+      class MiniRacerEngine
+        def initialize
+          require "mini_racer"
+          @context = MiniRacer::Context.new
+        end
+
+        def run(code)
+          @context.eval(code)
+        end
+
+        def drain
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/tailwindcss/version.rb

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

data/lib/rubocop-tailwindcss.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-# rubocop-tailwindcss is under development - this release reserves the name.
-# Follow along at https://github.com/am1006/tailwindcss-sorter
-module RuboCop
-  module Tailwindcss
-    VERSION = "0.0.1"
-  end
-end
+require "rubocop"
+
+require_relative "rubocop/tailwindcss/version"
+require_relative "rubocop/tailwindcss/plugin"
+require_relative "rubocop/tailwindcss/sorter"
+require_relative "rubocop/cop/tailwindcss/class_order"