classy-yaml 1.7.2 → 1.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97e19478fc64b51321f597e6449e4a6b72708391561401a1fcd8c09996f1ace2
-  data.tar.gz: 428fb76c90fea87eb601ab917fa86715e2ed0634669ab0ddf8e061da9087ac85
+  metadata.gz: 177a550a2cc9c2678b05d5ccfc29aeb690949e1e99f604bc78f4a728fac96fc9
+  data.tar.gz: 1afe8baf1045c0bc23e60916a0f4dba19cd8d39f0562ed60bd58e3a914613238
 SHA512:
-  metadata.gz: 8aef2b74c04eacb3573d5958108559f729965abc7766be1441dd903d62b2375f98e6b917e0d055fc8b0e2246bff4c959242ee8eacfa29a5c8827fdc725a85393
-  data.tar.gz: e2a5ce4eccecd4ada862ba28e98bd731b9e37ad54d6fb8060b5a06471cd906d805c78ec473f426a5a98de49078c3df65cffbc780171a557d66151793b3d91743
+  metadata.gz: ec10f751c02f2e49cd8aa176a0b0361a82c0a7feb0cc7a68518cadf94c6008b39efd5b1c3b210c699c01cd4f6517d3af3e97231f3d115d98313fe7ba1ce20eea
+  data.tar.gz: 6b9e997a94be56439b79765aef5117b54cac23e40681634bc56666413ca68a29debdce78cab0ccf83a0b77f4d7c8c3260dbdb99419fb0b0fe5dbdd02d87ae2e2

data/README.md

@@ -144,11 +144,14 @@ Classy YAML detects if [tailwind_merge](https://github.com/gjtorikian/tailwind_m
 
 ## Caching and development reloads
 
-Classy YAML reuses parsed YAML when file metadata has not changed. In development and tests, each call checks the default, engine, extra, and component files. Edits, additions, and deletions take effect on the next call without a restart.
+Classy YAML needs no configuration for its caches. The railtie chooses their behavior from `Rails.application.config.cache_classes`.
 
-In production, the default and engine YAML remain cached until configuration resets or the process restarts. Extra and component files still receive metadata checks. `Classy::Yaml.setup` clears the YAML caches.
+- **Results.** `yass` remembers the result for each set of arguments (including `add:`, `skip_base:` and `classy_files:`) in a bounded least-recently-used cache of `Classy::Yaml.cache_size` entries (5,000 by default). A repeated call does no YAML lookup and no class merge. A call that logs an invalid key warning is not cached, so the warning appears on every call. Set `Classy::Yaml.cache_size = 0` to turn the result cache off.
+- **YAML files.** Each file is parsed once and compiled to frozen lookup data. A missing or invalid file is also remembered.
+- **Classes cached (test, production).** Classy YAML never checks the files again. Edits take effect after a restart or `Classy::Yaml.setup`. At boot, Classy YAML parses the default, engine, and extra files and builds the `tailwind_merge` merger, so forked workers (Puma `preload_app!`, parallel tests) share them.
+- **Classes reloaded (development).** At the start of each request or job (the Rails executor), Classy YAML marks its files for a check. The next `yass` call checks each YAML file it has read once, including missing component files. An edit, addition, deletion, or replacement takes effect on the next request. Outside the executor, for example in a console, call `reload!`.
 
-When `tailwind_merge` is available, Classy YAML reuses one merger per process in all environments. A lock protects the merger cache during concurrent calls.
+`Classy::Yaml.setup` and the file setters clear all caches. When `tailwind_merge` is available, Classy YAML reuses one merger per process in all environments. A lock protects the merger cache during concurrent calls.
 
 ## Configuration Options
 
@@ -158,6 +161,7 @@ When `tailwind_merge` is available, Classy YAML reuses one merger per process in
 | `extra_files` | `[]` | Array of additional YAML files (above default and engine files; below component files) |
 | `engine_files` | `[]` | Array of engine YAML files (lowest priority) |
 | `override_tag_helpers` | `false` | Automatically process class symbols/hashes in Rails tag helpers |
+| `cache_size` | `5000` | Maximum number of cached `yass` results; `0` turns the result cache off |
 
 ## Contributing
 

data/lib/classy/yaml/component_helpers.rb

@@ -2,19 +2,12 @@ module Classy
   module Yaml
     module ComponentHelpers
       def yass(*args)
-        source_file = Object.const_source_location(self.class.name).first
-        calling_path = File.dirname(source_file)
-        calling_file = File.basename(source_file).split(".").first
-        component_name = self.class.name.underscore.split("/").last.split(".").first
-
-        classy_files = [ "#{calling_path}/#{component_name}.yml",
-                        "#{calling_path}/#{calling_file}/#{calling_file}.yml",
-                        "#{calling_path}/#{calling_file}/#{component_name}.yml" ]
+        classy_files = Classy::Yaml.component_classy_files(self.class)
 
         if args.first.is_a?(Hash)
-          args[0] = args.first.merge(classy_files: classy_files.uniq)
+          args[0] = args.first.merge(classy_files: classy_files)
         else
-          args << { classy_files: classy_files.uniq }
+          args << { classy_files: classy_files }
         end
 
         helpers.yass(*args)

data/lib/classy/yaml/engine.rb

@@ -3,9 +3,22 @@ require "rails"
 module Classy
   module Yaml
     class Engine < Rails::Railtie
+      # Each request or job starts with one check of the YAML files while Rails
+      # reloads code, instead of a check on every lookup.
+      initializer "classy_yaml.file_check" do |app|
+        app.executor.to_run { Classy::Yaml.files_may_have_changed }
+      end
+
       config.to_prepare do
+        Classy::Yaml.clear_component_files
+        Classy::Yaml.files_may_have_changed
         ApplicationController.helper(Classy::Yaml::Helpers)
       end
+
+      # With classes cached, parse the YAML before workers fork.
+      config.after_initialize do |app|
+        Classy::Yaml.warm if app.config.cache_classes
+      end
     end
   end
 end

data/lib/classy/yaml/helpers.rb

@@ -11,154 +11,17 @@ module Classy
       # @param args [Array] Array of keys to look up in the YAML files
       # @return [String] Space-separated list of CSS classes
       def yass(*args)
-        # Start with engine YAMLs (lowest priority)
-        classy_yamls = Classy::Yaml.cached_engine_yamls.dup
-
-        # Add default YAML (next priority)
-        default_yaml = Classy::Yaml.cached_default_yaml
-        classy_yamls << default_yaml if default_yaml
-
-        # Add extra files (highest priority)
-        Classy::Yaml.extra_files.each do |file_path|
-          load_yaml_file(file_path, classy_yamls, "extra")
-        end
-
-        # Add classy_files (highest priority)
-        classy_files_hash = args.find { |arg| arg.is_a?(Hash) && arg.key?(:classy_files) } || { classy_files: [] }
-        classy_files_hash[:classy_files].each do |file_path|
-          load_yaml_file(file_path, classy_yamls, "classy")
-        end
-
-        skip_base_hash = args.find { |arg| arg.is_a?(Hash) && arg.key?(:skip_base) } || {}
-        keys, add_classes = flatten_args(values: args)
-        classes = fetch_classes(keys.uniq, classy_yamls: classy_yamls, skip_base: skip_base_hash[:skip_base])
-        classes += add_classes
-
-        # Use tailwind_merge if available, otherwise fall back to simple join
-        merge_classes(classes.flatten.uniq)
+        Classy::Yaml.classes_for(args, tailwind_merge_available?)
       end
 
       private
 
-      # Merges CSS classes using tailwind_merge if available, otherwise uses simple join
-      # @param classes [Array] Array of CSS class strings
-      # @return [String] Merged CSS classes
-      def merge_classes(classes)
-        return "" if classes.blank?
-
-        if tailwind_merge_available?
-          # Use tailwind_merge for intelligent class merging
-          Classy::Yaml.merge_classes(classes)
-        else
-          # Fall back to simple space-joined classes
-          classes.join(" ")
-        end
-      end
-
       # Checks if tailwind_merge gem is available
       # @return [Boolean] True if tailwind_merge is available
       def tailwind_merge_available?
         return @tailwind_merge_available if defined?(@tailwind_merge_available)
-        @tailwind_merge_available = begin
-          require "tailwind_merge"
-          true
-        rescue LoadError
-          false
-        end
-      end
-
-      # Loads a YAML file and adds its contents to the classy_yamls array
-      # @param file_path [String, Pathname] Path to the YAML file
-      # @param classy_yamls [Array] Array to add the parsed YAML to
-      # @param file_type [String] Type of file being loaded (for error messages)
-      def load_yaml_file(file_path, classy_yamls, file_type)
-        parsed_yaml = Classy::Yaml.cached_yaml_file(file_path, file_type)
-        classy_yamls << parsed_yaml if parsed_yaml
-      end
-
-      # Flattens the arguments into keys and classes
-      # @param root [Array] Current root path in the argument tree
-      # @param values [Array] Values to process
-      # @param keys [Array] Array to store found keys
-      # @param added_classes [Array] Array to store found classes
-      # @return [Array] Tuple of [keys, added_classes]
-      def flatten_args(root: [], values: [], keys: [], added_classes: [])
-        parent_keys = []
-        values.each do |value|
-          case value
-          when Hash
-            added_classes << value[:add] if value.key?(:add)
-            value.each do |key, child|
-              next if key == :add
-              next if root.empty? && [ :skip_base, :classy_files ].include?(key)
-
-              path = root + [ key.to_s ]
-              parent_keys << path
-              flatten_args(root: path, values: [ child ], keys: keys, added_classes: added_classes)
-            end
-          when Array
-            flatten_args(root: root, values: value, keys: keys, added_classes: added_classes)
-          else
-            keys << (root + [ value.to_s ])
-          end
-        end
-        keys.concat(parent_keys)
-        [ keys, added_classes ]
-      end
-
-      # Fetches classes from the YAML files based on the provided keys
-      # @param keys [Array] Array of keys to look up
-      # @param classy_yamls [Array] Array of YAML files to search in
-      # @param skip_base [Boolean] Whether to skip base classes
-      # @return [Array] Array of found classes
-      def fetch_classes(keys, classy_yamls: [], skip_base: false)
-        classes = []
-
-        keys.each do |key|
-          base_classes = nil
-          fetched_classes = nil
-
-          classy_yamls.reverse_each do |classy_yaml|
-            begin
-              value = classy_yaml.dig(*key)
-              unless skip_base == true || base_classes
-                base_value = if value.is_a?(Hash)
-                  value["base"]
-                elsif key.length > 1
-                  classy_yaml.dig(*(key[0...-1] + [ "base" ]))
-                end
-                base_classes = normalize_original(base_value).presence
-              end
-
-              unless fetched_classes || value.is_a?(Hash)
-                fetched_classes = normalize_original(value).presence
-              end
-            rescue StandardError
-              Rails.logger.warn(Classy::Yaml::InvalidKeyError.new(data: key))
-            end
-
-            break if fetched_classes && (skip_base == true || base_classes)
-          end
-
-          classes << base_classes unless base_classes.blank?
-          classes << fetched_classes unless fetched_classes.blank?
-        end
-
-        classes.flatten.uniq
-      end
 
-      # Normalizes a value into an array of classes
-      # @param value [String, Array, nil] Value to normalize
-      # @return [Array, nil] Array of classes or nil if value is invalid
-      def normalize_original(value)
-        case value
-        when String
-          value.split(" ").reject(&:blank?)
-        when Array
-          value.flatten.map(&:to_s).reject(&:blank?)
-        else
-          nil
-        end
+        Classy::Yaml.tailwind_merge_available?
       end
     end
   end

data/lib/classy/yaml/lookup.rb

@@ -0,0 +1,181 @@
+module Classy
+  module Yaml
+    # Turns yass arguments into classes. The YAML layers are compiled once at load
+    # (see Classy::Yaml.compile), so a lookup only walks frozen hashes and arrays.
+    module Lookup
+      EMPTY = [].freeze
+      # Returned by walk when a key path goes through a value that is not a hash.
+      INVALID = Object.new.freeze
+      # A compiled YAML array that refers to itself. 1.7.2 raised on it while
+      # normalizing classes, so using it logs a warning and skips the layer.
+      RECURSIVE = Object.new.freeze
+      # Cache key markers. Hash order changes the output, so a key lists hash
+      # entries in order instead of using Hash#eql?, which ignores order.
+      HASH_START = Object.new.freeze
+      ARRAY_START = Object.new.freeze
+      CLOSE = Object.new.freeze
+
+      module_function
+
+      # Returns an order-sensitive cache key for the arguments, or nil when an
+      # argument is not a plain value. Only the exact core classes qualify: a
+      # subclass can override #to_s, #each or #key? and change the result.
+      def cache_key(args, tailwind)
+        key = [ tailwind ]
+        append_key(args, key) ? key : nil
+      end
+
+      def append_key(value, key)
+        case value
+        when Symbol, Integer, Float, nil, true, false
+          key << value
+        when String, Pathname
+          return false unless value.instance_of?(String) || value.instance_of?(Pathname)
+
+          key << value
+        when Array
+          return false unless value.instance_of?(Array)
+
+          key << ARRAY_START
+          value.each { |child| return false unless append_key(child, key) }
+          key << CLOSE
+        when Hash
+          return false unless value.instance_of?(Hash)
+
+          key << HASH_START
+          value.each { |name, child| return false unless append_key(name, key) && append_key(child, key) }
+          key << CLOSE
+        else
+          return false
+        end
+        true
+      end
+
+      # Freezes a cache key built by cache_key. Unfrozen strings are replaced by
+      # frozen copies, so a caller that later mutates its strings cannot change it.
+      def freeze_key(key)
+        key.each_with_index do |part, index|
+          key[index] = part.dup.freeze if part.is_a?(String) && !part.frozen?
+        end
+        key.freeze
+      end
+
+      # Collects the lookup key paths and add: values in the order 1.7.2 used:
+      # leaf paths first, then the parent paths of each list of values.
+      def collect_list(values, root, keys, adds)
+        parents = nil
+        values.each { |value| parents = collect(value, root, keys, adds, parents) }
+        keys.concat(parents) if parents
+      end
+
+      def collect(value, root, keys, adds, parents)
+        case value
+        when Hash
+          adds << value[:add] if value.key?(:add)
+          value.each do |name, child|
+            next if name == :add
+            next if root.empty? && (name == :skip_base || name == :classy_files)
+
+            path = [ *root, segment(name) ]
+            (parents ||= []) << path
+            nested = collect(child, path, keys, adds, nil)
+            keys.concat(nested) if nested
+          end
+        when Array
+          collect_list(value, root, keys, adds)
+        else
+          keys << [ *root, segment(value) ]
+        end
+        parents
+      end
+
+      def segment(value)
+        value.is_a?(Symbol) ? value.name : value.to_s
+      end
+
+      # Resolves each key path against the layers (lowest priority first) and
+      # appends base and specific classes. Returns false when a path went through
+      # a value that is not a hash; that call logged a warning.
+      def resolve(keys, layers, skip_base, classes)
+        clean = true
+        skip_base = skip_base == true
+        keys.each do |path|
+          clean = false unless resolve_path(path, layers, skip_base, classes)
+        end
+        clean
+      end
+
+      def resolve_path(path, layers, skip_base, classes)
+        clean = true
+        base_classes = nil
+        fetched_classes = nil
+        last = path.size - 1
+        index = layers.size - 1
+        while index >= 0
+          layer = layers[index]
+          index -= 1
+          parent = walk(layer, path, last)
+          value = case parent
+          when Hash then parent[path[last]]
+          when nil then nil
+          else INVALID
+          end
+
+          if value.equal?(INVALID)
+            clean = false
+            Rails.logger.warn(Classy::Yaml::InvalidKeyError.new(data: path))
+          else
+            # 1.7.2 computed the base, then the classes, and a recursive array
+            # raised in either step, which skipped the rest of this layer.
+            unless skip_base || base_classes
+              base_value = if value.is_a?(Hash)
+                value["base"]
+              elsif last.positive? && parent.is_a?(Hash)
+                parent["base"]
+              end
+              base_classes = classes_of(base_value)
+            end
+            unless fetched_classes || value.is_a?(Hash) || base_classes.equal?(RECURSIVE)
+              fetched_classes = classes_of(value)
+            end
+            if base_classes.equal?(RECURSIVE) || fetched_classes.equal?(RECURSIVE)
+              base_classes = nil if base_classes.equal?(RECURSIVE)
+              fetched_classes = nil if fetched_classes.equal?(RECURSIVE)
+              clean = false
+              Rails.logger.warn(Classy::Yaml::InvalidKeyError.new(data: path))
+            end
+          end
+
+          break if fetched_classes && (skip_base || base_classes)
+        end
+
+        classes.concat(base_classes) if base_classes
+        classes.concat(fetched_classes) if fetched_classes
+        clean
+      end
+
+      # Follows path[0...depth] from node. Returns nil when a key is missing, and
+      # INVALID when the path continues through a value that is not a hash.
+      def walk(node, path, depth)
+        index = 0
+        while index < depth
+          case node
+          when Hash then node = node[path[index]]
+          when nil then return nil
+          else return INVALID
+          end
+          index += 1
+        end
+        node
+      end
+
+      # A compiled leaf is a frozen array of classes; anything else has none.
+      # A recursive array is returned as RECURSIVE for the caller to report.
+      def classes_of(value)
+        return value if value.equal?(RECURSIVE)
+
+        value if value.is_a?(Array) && !value.empty?
+      end
+    end
+  end
+end

data/lib/classy/yaml/result_cache.rb

@@ -0,0 +1,68 @@
+module Classy
+  module Yaml
+    # A bounded, thread-safe least-recently-used cache of yass results.
+    #
+    # Entries are indexed by the key's hash, computed once per call, and keep the
+    # key itself so a lookup only hits when the keys are eql?. A store carries the
+    # generation its result was computed under; a store from an older generation
+    # is dropped, so a lookup that raced a reload or a `setup` never caches an
+    # answer built from the old YAML.
+    class ResultCache
+      Entry = Struct.new(:key, :value)
+
+      attr_reader :max_size
+
+      def initialize(max_size)
+        @max_size = max_size
+        @entries = {}
+        @generation = 0
+        @lock = Mutex.new
+      end
+
+      def generation
+        @generation
+      end
+
+      def max_size=(value)
+        @lock.synchronize do
+          @max_size = value
+          @entries.shift while @entries.size > @max_size
+        end
+      end
+
+      def size
+        @entries.size
+      end
+
+      def get(key, digest = key.hash)
+        @lock.synchronize do
+          entry = @entries.delete(digest)
+          return unless entry
+
+          # Move the entry to the newest end; a colliding key is a miss and its
+          # entry is replaced by the next store.
+          @entries[digest] = entry
+          entry.value if entry.key.eql?(key)
+        end
+      end
+
+      def store(key, value, generation, digest = key.hash)
+        @lock.synchronize do
+          return unless generation == @generation && @max_size.positive?
+
+          @entries.delete(digest)
+          @entries[digest] = Entry.new(key, value).freeze
+          @entries.shift if @entries.size > @max_size
+        end
+      end
+
+      # Drops every result and invalidates stores already in progress.
+      def invalidate
+        @lock.synchronize do
+          @generation += 1
+          @entries.clear
+        end
+      end
+    end
+  end
+end

data/lib/classy/yaml/version.rb

@@ -1,5 +1,5 @@
 module Classy
   module Yaml
-    VERSION = "1.7.2"
+    VERSION = "1.7.3"
   end
 end

data/lib/classy/yaml.rb

@@ -1,3 +1,4 @@
+require "concurrent/map"
 require "classy/yaml/version"
 require "classy/yaml/engine"
 
@@ -20,29 +21,42 @@ module Classy
     autoload :Helpers, "classy/yaml/helpers"
     autoload :ComponentHelpers, "classy/yaml/component_helpers"
     autoload :InvalidKeyError, "classy/yaml/invalid_key_error"
+    autoload :Lookup, "classy/yaml/lookup"
+    autoload :ResultCache, "classy/yaml/result_cache"
 
-    # -- Class Instance Variables for Caching --
-    @cached_engine_yamls = nil
-    @cached_default_yaml = nil
-    @load_lock = Mutex.new # Prevent race conditions during lazy loading
+    # The number of yass results kept for reuse. Set to 0 to turn the result cache off.
+    DEFAULT_CACHE_SIZE = 5_000
+
+    FileEntry = Struct.new(:signature, :layer)
+
+    # -- Caches --
+    # Parsed and compiled YAML files, keyed by full path. While Rails reloads code,
+    # each entry keeps the file signature that check_for_changes compares.
     @file_cache = {}
+    # Configured and component paths resolved against Rails.root.
+    @full_paths = {}
     @file_lock = Mutex.new
+    # The engine, default and extra layers, compiled for the current generation.
+    @static_layers = nil
+    @results = ResultCache.new(DEFAULT_CACHE_SIZE)
+    @component_files = Concurrent::Map.new
+    @check_pending = false
     @merger_lock = Mutex.new
 
     # -- Configuration Setters with Path Resolution --
     def self.engine_files=(value)
       @@engine_files = Array.wrap(value).reject(&:blank?).map { |file| Rails.root.join(file) }
-      @cached_engine_yamls = nil # Clear cache on reassignment
+      reset_caches
     end
 
     def self.extra_files=(value)
       @@extra_files = Array.wrap(value).reject(&:blank?).map { |file| Rails.root.join(file) }
-      # Parsed files use the shared file cache.
+      reset_caches
     end
 
     def self.default_file=(value)
       @@default_file = value
-      @cached_default_yaml = nil # Clear cache on reassignment
+      reset_caches
     end
 
     def self.override_tag_helpers=(value)
@@ -50,109 +64,167 @@ module Classy
       apply_tag_helper_override if value
     end
 
-    # -- Cached Data Accessors (Lazy Loading) --
-    def self.cached_engine_yamls
-      # Check file metadata only while Rails reloads code
-      return load_engine_yamls if reloading?
-
-      # Classes are cached: parse once
-      return @cached_engine_yamls if @cached_engine_yamls
-
-      @load_lock.synchronize do
-        # Double-check idiom to ensure loading happens only once
-        return @cached_engine_yamls if @cached_engine_yamls
-        @cached_engine_yamls = load_engine_yamls
-      end
+    def self.cache_size
+      @results.max_size
     end
 
-    def self.cached_default_yaml
-      # Check file metadata only while Rails reloads code
-      return load_default_yaml if reloading?
+    # Accepts an Integer, or a String holding one (for example from ENV), of 0 or more.
+    # Integer() would truncate a Float such as -0.5 to 0, so floats are rejected.
+    def self.cache_size=(value)
+      size = case value
+      when Integer then value
+      when String then Integer(value, 10, exception: false)
+      end
+      unless size && !size.negative?
+        raise ArgumentError, "Classy::Yaml.cache_size must be an integer of 0 or more, got #{value.inspect}"
+      end
 
-      # Classes are cached: parse once
-      return @cached_default_yaml if @cached_default_yaml
+      @results.max_size = size
+    end
 
-      @load_lock.synchronize do
-        return @cached_default_yaml if @cached_default_yaml
-        @cached_default_yaml = load_default_yaml
-      end
+    # Increases on every configuration change and every YAML file change.
+    def self.generation
+      @results.generation
     end
 
     # -- Setup Method --
     def self.setup
       yield self
       # Clear all caches when configuration changes
-      @cached_engine_yamls = nil
-      @cached_default_yaml = nil
-      @file_lock.synchronize { @file_cache.clear }
+      reset_caches(files: true)
       # Apply tag helper override if enabled
       apply_tag_helper_override if @@override_tag_helpers
     end
 
-    private
+    # Returns the classes for yass arguments. Results are reused until a
+    # configuration change or (while Rails reloads code) a YAML file change.
+    def self.classes_for(args, tailwind)
+      check_for_changes if @check_pending
+      key = Lookup.cache_key(args, tailwind) if @results.max_size.positive?
+      if key
+        digest = key.hash
+        cached = @results.get(key, digest)
+        return cached.is_a?(String) ? cached : cached.first.dup if cached
+      end
 
-    def self.apply_tag_helper_override
-      require "classy/yaml/tag_helper"
+      generation = @results.generation
+      result, cacheable = build_classes(args, tailwind)
+      if key && cacheable
+        # A frozen result is shared as 1.7.2 shared tailwind_merge's cached string;
+        # any other result is returned as a new unfrozen copy each time.
+        value = result.frozen? ? result : [ result.dup.freeze ].freeze
+        @results.store(Lookup.freeze_key(key), value, generation, digest)
+      end
+      result
+    end
 
-      ActiveSupport.on_load(:action_view) do
-        ActionView::Helpers::TagHelper::TagBuilder.prepend(Classy::Yaml::TagHelper)
+    # Parses the YAML files and builds the merger before Puma or the test runner
+    # forks, so workers share them copy-on-write and the first request pays nothing.
+    def self.warm
+      static_layers
+      @merger_lock.synchronize { @merger ||= TailwindMerge::Merger.new } if tailwind_merge_available?
+    end
+
+    # Called at the start of each request or job (the Rails executor) and after
+    # each code reload (to_prepare, which also covers `reload!` in a console).
+    # While Rails reloads code, the next lookup compares each YAML file it has
+    # read. With classes cached it does nothing, so no file is ever checked.
+    def self.files_may_have_changed
+      @check_pending = true if reloading?
+    end
+
+    # Stats every YAML file read so far (also missing ones) once. A change drops
+    # that file and every cached result (a new generation).
+    #
+    # Not ActiveSupport::FileUpdateChecker, for two reasons:
+    # - It detects an edit only when the newest mtime of all watched files grows
+    #   (or the number of existing files changes). An edit that keeps the mtime,
+    #   or a replacement by an older file, is missed.
+    # - Its files and directories are fixed when it is built, but component YAML
+    #   paths are discovered at the first render, so each new path would need a
+    #   new checker.
+    # The signature here is mtime, ctime, size, inode and device of each file
+    # looked up so far, and nil for a missing one.
+    def self.check_for_changes
+      @file_lock.synchronize do
+        return unless @check_pending
+
+        @check_pending = false
+        changed = @file_cache.select { |path, entry| entry.signature != file_signature(path) }
+        next if changed.empty?
+
+        changed.each_key { |path| @file_cache.delete(path) }
+        invalidate_results
       end
+    end
 
-      apply_icon_helper_override
+    def self.reset_caches(files: false)
+      @file_lock.synchronize do
+        if files
+          @file_cache.clear
+          @full_paths.clear
+        end
+        @component_files = Concurrent::Map.new
+        invalidate_results
+      end
     end
 
-    def self.apply_icon_helper_override
-      return unless defined?(RailsIcons::Helpers::IconHelper)
+    # Must be called with @file_lock held.
+    def self.invalidate_results
+      @static_layers = nil
+      @results.invalidate
+    end
 
-      require "classy/yaml/icon_helper"
+    def self.tailwind_merge_available?
+      return @tailwind_merge_available if defined?(@tailwind_merge_available)
 
-      RailsIcons::Helpers::IconHelper.prepend(Classy::Yaml::IconHelper)
+      @tailwind_merge_available = begin
+        require "tailwind_merge"
+        true
+      rescue LoadError
+        false
+      end
     end
 
-    def self.load_engine_yamls
-      engine_files.map { |path| cached_yaml_file(path, "engine") }.compact
+    # The YAML candidates next to a component's source file, computed once per class.
+    def self.component_classy_files(component_class)
+      @component_files.compute_if_absent(component_class) do
+        source_file = Object.const_source_location(component_class.name).first
+        calling_path = File.dirname(source_file)
+        calling_file = File.basename(source_file).split(".").first
+        component_name = component_class.name.underscore.split("/").last.split(".").first
+
+        [ "#{calling_path}/#{component_name}.yml",
+          "#{calling_path}/#{calling_file}/#{calling_file}.yml",
+          "#{calling_path}/#{calling_file}/#{component_name}.yml" ].uniq.each(&:freeze).freeze
+      end
     end
 
-    def self.load_default_yaml
-      cached_yaml_file(default_file, "default")
+    # Reloaded component classes are new objects, so drop the old ones.
+    def self.clear_component_files
+      @component_files = Concurrent::Map.new
     end
 
-    # Edits are picked up without a restart only while Rails reloads code.
-    # With classes cached (test, production) a parsed file is never stat'ed again.
-    def self.reloading?
-      !Rails.application.config.cache_classes
+    # Engine files (lowest priority), the default file, then extra files.
+    def self.static_layers
+      @static_layers || begin
+        generation = @results.generation
+        layers = [
+          *engine_files.map { |path| cached_yaml_file(path, "engine") },
+          cached_yaml_file(default_file, "default"),
+          *extra_files.map { |path| cached_yaml_file(path, "extra") }
+        ].compact.freeze
+        @file_lock.synchronize { @static_layers = layers if generation == @results.generation }
+        layers
+      end
     end
 
-    # Check metadata on each access while reloading so edits do not require a restart.
+    # Returns the compiled YAML of a file, or nil when it is missing or invalid.
     def self.cached_yaml_file(file_path, file_type)
       @file_lock.synchronize do
-        begin
-          path = Rails.root.join(file_path).to_s
-          cached = @file_cache[path]
-          return cached[:yaml] if cached && !reloading?
-
-          stat = File.stat(path)
-          signature = [ stat.mtime, stat.ctime, stat.size, stat.ino, stat.dev ]
-          return cached[:yaml] if cached && cached[:signature] == signature
-
-          content = File.read(path, encoding: "UTF-8")
-          parsed = YAML.safe_load(content, permitted_classes: [ Symbol, String, Array, Hash ], aliases: true)
-          yaml = parsed.is_a?(Hash) ? parsed : nil
-          @file_cache[path] = { signature: signature, yaml: yaml }
-          yaml
-        rescue Errno::ENOENT, Errno::ENOTDIR
-          # A missing file stays missing until the next restart when classes are cached.
-          reloading? ? @file_cache.delete(path) : @file_cache[path] = { signature: nil, yaml: nil }
-          nil
-        rescue Psych::SyntaxError => e
-          @file_cache.delete(path)
-          Rails.logger.error "Classy::Yaml: Failed to parse #{file_type} YAML file #{file_path}: #{e.message}"
-          nil
-        rescue => e
-          @file_cache.delete(path)
-          Rails.logger.error "Classy::Yaml: Error loading #{file_type} YAML file #{file_path}: #{e.message}"
-          nil
-        end
+        path = @full_paths[file_path] ||= Rails.root.join(file_path).to_s.freeze
+        entry = @file_cache[path] ||= load_yaml_file(path, file_path, file_type)
+        entry.layer
       end
     end
 
@@ -163,5 +235,116 @@ module Classy
         @merger.merge(classes)
       end
     end
+
+    # Edits are picked up without a restart only while Rails reloads code.
+    # With classes cached (test, production) a parsed file is never stat'ed again.
+    def self.reloading?
+      !Rails.application.config.cache_classes
+    end
+
+    # Turns parsed YAML into frozen lookup data: a string becomes its classes, an
+    # array its flattened classes. Other values stay as they are and give no classes.
+    def self.compile(value, compiled_hashes = {}.compare_by_identity)
+      case value
+      when Hash
+        compiled_hashes[value] || begin
+          compiled = compiled_hashes[value] = {}
+          value.each { |key, child| compiled[key] = compile(child, compiled_hashes) }
+          compiled.freeze
+        end
+      when String
+        value.split(" ").reject(&:blank?).each(&:freeze).freeze
+      when Array
+        begin
+          value.flatten.map(&:to_s).reject(&:blank?).each(&:freeze).freeze
+        rescue ArgumentError
+          # flatten raises on a recursive array; lookups report it as 1.7.2 did.
+          Lookup::RECURSIVE
+        end
+      else
+        value
+      end
+    end
+
+    def self.apply_tag_helper_override
+      require "classy/yaml/tag_helper"
+
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Helpers::TagHelper::TagBuilder.prepend(Classy::Yaml::TagHelper)
+      end
+
+      apply_icon_helper_override
+    end
+
+    def self.apply_icon_helper_override
+      return unless defined?(RailsIcons::Helpers::IconHelper)
+
+      require "classy/yaml/icon_helper"
+
+      RailsIcons::Helpers::IconHelper.prepend(Classy::Yaml::IconHelper)
+    end
+
+    class << self
+      private
+
+      def build_classes(args, tailwind)
+        layers = static_layers
+        classy_files = args.find { |arg| arg.is_a?(Hash) && arg.key?(:classy_files) }
+        if classy_files
+          layers = layers.dup
+          classy_files[:classy_files].each do |file_path|
+            layer = cached_yaml_file(file_path, "classy")
+            layers << layer if layer
+          end
+        end
+        skip_base = args.find { |arg| arg.is_a?(Hash) && arg.key?(:skip_base) }
+
+        keys = []
+        adds = []
+        Lookup.collect_list(args, Lookup::EMPTY, keys, adds)
+        keys.uniq!
+        classes = []
+        clean = Lookup.resolve(keys, layers, skip_base && skip_base[:skip_base], classes)
+        classes.uniq!
+        unless adds.empty?
+          classes.concat(adds)
+          classes.flatten!
+          classes.uniq!
+        end
+
+        result = if classes.empty?
+          +""
+        elsif tailwind
+          merge_classes(classes)
+        else
+          classes.join(" ")
+        end
+        [ result, clean ]
+      end
+
+      def load_yaml_file(path, file_path, file_type)
+        signature = file_signature(path)
+        return FileEntry.new(nil, nil).freeze unless signature
+
+        content = File.read(path, encoding: "UTF-8")
+        parsed = YAML.safe_load(content, permitted_classes: [ Symbol, String, Array, Hash ], aliases: true)
+        FileEntry.new(signature, parsed.is_a?(Hash) ? compile(parsed) : nil).freeze
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        FileEntry.new(nil, nil).freeze
+      rescue Psych::SyntaxError => e
+        Rails.logger.error "Classy::Yaml: Failed to parse #{file_type} YAML file #{file_path}: #{e.message}"
+        FileEntry.new(signature, nil).freeze
+      rescue => e
+        Rails.logger.error "Classy::Yaml: Error loading #{file_type} YAML file #{file_path}: #{e.message}"
+        FileEntry.new(signature, nil).freeze
+      end
+
+      def file_signature(path)
+        stat = File.stat(path)
+        [ stat.mtime, stat.ctime, stat.size, stat.ino, stat.dev ]
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        nil
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: classy-yaml
 version: !ruby/object:Gem::Version
-  version: 1.7.2
+  version: 1.7.3
 platform: ruby
 authors:
 - Tonksthebear
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -152,6 +152,8 @@ files:
 - lib/classy/yaml/helpers.rb
 - lib/classy/yaml/icon_helper.rb
 - lib/classy/yaml/invalid_key_error.rb
+- lib/classy/yaml/lookup.rb
+- lib/classy/yaml/result_cache.rb
 - lib/classy/yaml/tag_helper.rb
 - lib/classy/yaml/version.rb
 - lib/tasks/classy/yaml_tasks.rake