react-manifest-rails 0.2.28 → 0.2.30

data/lib/react_manifest/scanner.rb

@@ -1,3 +1,5 @@
+require_relative "path_utils"
+
 module ReactManifest
   # Scans JS/JSX (and optionally TS/TSX) files using regex — no AST, no Node.js required.
   #
@@ -16,63 +18,56 @@ module ReactManifest
   # Phase 3 — emits non-fatal warnings.
   # rubocop:disable Metrics/ClassLength
   class Scanner
-    # Patterns to detect symbol definitions (CommonJS and ES module style)
-    DEFINITION_PATTERNS = [
-      # CommonJS / variable-assignment style
-      /(?:const|let|var)\s+([A-Z][A-Za-z0-9_]*)\s*=/, # const FooBar =
-      /function\s+([A-Z][A-Za-z0-9_]*)\s*\(/,         # function FooBar(
-      /class\s+([A-Z][A-Za-z0-9_]*)\s*(?:extends|\{)/, # class FooBar
-      /(?:const|let|var)\s+(use[A-Z][A-Za-z0-9_]*)\s*=/, # const useFoo = (hooks)
-      /function\s+(use[A-Z][A-Za-z0-9_]*)\s*\(/, # function useFoo(
-
-      # ES module style (export default / named exports)
-      /^export\s+default\s+(?:function|class)\s+([A-Z][A-Za-z0-9_]*)/,
-      /^export\s+default\s+(?:function|class)\s+(use[A-Z][A-Za-z0-9_]*)/,
-      /^export\s+(?:const|let|var)\s+([A-Z][A-Za-z0-9_]*)\s*=/,
-      /^export\s+(?:const|let|var)\s+(use[A-Z][A-Za-z0-9_]*)\s*=/,
-      /^export\s+function\s+([A-Z][A-Za-z0-9_]*)\s*\(/,
-      /^export\s+function\s+(use[A-Z][A-Za-z0-9_]*)\s*\(/,
-      /^export\s+class\s+([A-Z][A-Za-z0-9_]*)\s*(?:extends|\{)/
-    ].freeze
-
-    # Patterns to detect usage in controller files.
-    # Token-based patterns match any identifier occurrence regardless of syntax
-    # context (JSX, constructor, assignment, array, function argument, etc.).
-    PASCAL_TOKEN_PATTERN = /\b([A-Z][A-Za-z0-9_]*)\b/
-    HOOK_TOKEN_PATTERN   = /\b(use[A-Z][A-Za-z0-9_]*)\b/
-    # Lib calls matched against known lib symbols to reduce false positives
-    LIB_CALL_PATTERN     = /\b([a-z][A-Za-z0-9_]{2,})\s*\(/
-
-    # Common JS built-ins to exclude from lib-call matching
-    JS_BUILTINS = %w[
-      require function return typeof instanceof delete void
-      console document window location history navigator
-      setTimeout setInterval clearTimeout clearInterval
-      parseInt parseFloat isNaN isFinite encodeURI decodeURI
-      fetch Promise Object Array String Number Boolean Math JSON
-      Object Array String Number Boolean Symbol Map Set WeakMap
-    ].freeze
+    include PathUtils
+    include ReactManifest::Logging
+
+    DEFINITION_PATTERNS = SymbolExtractor::DEFINITION_PATTERNS
+    PASCAL_TOKEN_PATTERN = SymbolExtractor::PASCAL_TOKEN_PATTERN
+    HOOK_TOKEN_PATTERN   = SymbolExtractor::HOOK_TOKEN_PATTERN
+    LIB_CALL_PATTERN     = SymbolExtractor::LIB_CALL_PATTERN
+    JS_BUILTINS          = SymbolExtractor::JS_BUILTINS
 
     Result = Struct.new(:symbol_index, :controller_usages, :warnings, :shared_violations,
                         :external_violations, keyword_init: true)
 
+    class << self
+      def file_symbol_cache
+        @file_symbol_cache ||= {}
+      end
+
+      def clear_cache!
+        @file_symbol_cache = {}
+      end
+
+      def invalidate(file_path)
+        file_symbol_cache.delete(file_path)
+      end
+    end
+
     def initialize(config = ReactManifest.configuration)
       @config = config
     end
 
-    # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
     def scan(classification)
       warnings      = Set.new
       symbol_index  = {}
       external_file_paths = {} # file_path => relative_require_path for external_roots files
 
-      # Phase 1a: index symbols from shared dirs
-      shared_file_paths = {} # file_path => relative_require_path for all shared files
+      # Phase 1a: index symbols from shared dirs; cache content for violation detection
+      shared_file_paths = {}    # file_path => relative_require_path
+      shared_file_content = {}  # file_path => raw content string
       classification.shared_dirs.each do |shared_dir|
         js_files_in(shared_dir[:path]).each do |file_path|
           relative = relative_require_path(file_path)
           shared_file_paths[file_path] = relative
-          symbols = extract_definitions(file_path)
+          content = begin
+            File.read(file_path, encoding: "utf-8")
+          rescue Errno::ENOENT, Errno::EACCES, Encoding::InvalidByteSequenceError
+            nil
+          end
+          shared_file_content[file_path] = content
+          symbols = extract_definitions_from(file_path, content)
           symbols.each do |sym|
             if symbol_index.key?(sym)
               warnings.add("Duplicate symbol '#{sym}' in #{relative} (already from #{symbol_index[sym]})")
@@ -101,31 +96,15 @@ module ReactManifest
         symbol_index[sym] = require_path
       end
 
-      # Phase 1d: build controller (app-dir) symbol index for violation detection
-      controller_symbol_index = {}
-      classification.controller_dirs.each do |ctrl|
-        js_files_in(ctrl[:path]).each do |file_path|
-          extract_definitions(file_path).each do |sym|
-            controller_symbol_index[sym] ||= {
-              file: relative_require_path(file_path),
-              controller: ctrl[:name]
-            }
-          end
-        end
-      end
+      log_debug "Shared symbol index: #{symbol_index.size} symbols indexed" if @config.verbose?
 
-      $stdout.puts "[ReactManifest] Shared symbol index: #{symbol_index.size} symbols indexed" if @config.verbose?
-
-      # Phase 1e: detect shared files that use app-dir (controller) symbols
-      shared_violations = detect_shared_violations(shared_file_paths, controller_symbol_index, warnings)
-      external_violations = detect_external_root_violations(external_file_paths, controller_symbol_index, warnings)
-
-      # Phase 2: scan controller dirs for usage
+      # Phase 2: single pass over controller dirs — build violation index AND detect usages
+      controller_symbol_index = {}
       controller_usages = {}
 
       classification.controller_dirs.each do |ctrl|
-        files   = js_files_in(ctrl[:path])
-        used    = Set.new
+        files = js_files_in(ctrl[:path])
+        used  = Set.new
 
         warnings.add("Controller dir '#{ctrl[:name]}' has no JS/JSX files") if files.empty? && @config.verbose?
 
@@ -133,13 +112,25 @@ module ReactManifest
           content = read_controller_file(file_path, warnings)
           next unless content
 
+          extract_definitions_from(file_path, content).each do |sym|
+            controller_symbol_index[sym] ||= {
+              file: relative_require_path(file_path),
+              controller: ctrl[:name]
+            }
+          end
+
           used.merge(extract_used_shared_paths(content, symbol_index))
         end
 
         controller_usages[ctrl[:name]] = used.to_a.sort
       end
 
-      # Phase 3: additional warnings
+      # Phase 3a: detect shared/external files that use app-dir (controller) symbols
+      shared_violations = detect_shared_violations(shared_file_paths, shared_file_content, controller_symbol_index,
+                                                   warnings)
+      external_violations = detect_external_root_violations(external_file_paths, controller_symbol_index, warnings)
+
+      # Phase 3b: additional warnings
       emit_fanout_warnings(controller_usages, warnings)
 
       Result.new(
@@ -150,7 +141,7 @@ module ReactManifest
         external_violations: external_violations
       )
     end
-    # rubocop:enable Metrics/MethodLength,Metrics/AbcSize,Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/MethodLength,Metrics/AbcSize
 
     private
 
@@ -159,22 +150,37 @@ module ReactManifest
 
       Dir.glob(File.join(dir, "**", @config.extensions_glob))
          .reject { |f| File.directory?(f) }
-         .reject { |f| excluded_path?(f) }
+         .reject { |f| @config.excluded_path?(f) }
          .sort
     end
 
-    # Returns true if the file path contains a segment matching any exclude_path.
-    def excluded_path?(abs_path)
-      parts = abs_path.split(File::SEPARATOR)
-      @config.exclude_paths.any? { |ep| parts.include?(ep) }
+    def extract_definitions(file_path)
+      cache = self.class.file_symbol_cache
+      return cache[file_path] if cache.key?(file_path)
+
+      cache[file_path] = scan_file_definitions(file_path)
     end
 
-    def extract_definitions(file_path)
+    # Like extract_definitions but uses pre-read content, populating the cache as a side-effect.
+    def extract_definitions_from(file_path, content)
+      cache = self.class.file_symbol_cache
+      return cache[file_path] if cache.key?(file_path)
+
+      cache[file_path] = parse_definitions(content)
+    end
+
+    def scan_file_definitions(file_path)
       begin
         content = File.read(file_path, encoding: "utf-8")
       rescue Errno::ENOENT, Errno::EACCES, Encoding::InvalidByteSequenceError
         return []
       end
+      parse_definitions(content)
+    end
+
+    def parse_definitions(content)
+      return [] unless content
+
       symbols = []
       DEFINITION_PATTERNS.each do |pattern|
         content.scan(pattern) { |m| symbols << m[0] }
@@ -186,35 +192,24 @@ module ReactManifest
       # Build relative to output_dir (configurable) rather than a hardcoded path.
       base = @config.abs_output_dir + File::SEPARATOR
       rel  = abs_path.sub(base, "")
-      # Strip Sprockets-understood extensions: .js.jsx/.jsx/.js -> logical path.
-      rel.sub(/\.js\.jsx$/, "").sub(/\.jsx$/, "").sub(/\.js$/, "")
+      strip_asset_extension(rel)
     end
 
-    def detect_shared_violations(shared_file_paths, controller_symbol_index, warnings)
+    def detect_shared_violations(shared_file_paths, shared_file_content, controller_symbol_index, warnings)
       violations = []
       shared_file_paths.each do |file_path, relative|
-        content = begin
-          File.read(file_path, encoding: "utf-8")
-        rescue Errno::ENOENT, Errno::EACCES, Encoding::InvalidByteSequenceError
-          next
-        end
-
-        local_syms = Set.new
-        DEFINITION_PATTERNS.each { |p| content.scan(p) { |m| local_syms << m[0] } }
-
-        [PASCAL_TOKEN_PATTERN, HOOK_TOKEN_PATTERN].each do |pattern|
-          content.scan(pattern) do |match|
-            sym = match[0]
-            next if local_syms.include?(sym)
-            next unless controller_symbol_index.key?(sym)
-
-            info = controller_symbol_index[sym]
-            violations << { shared_file: relative, symbol: sym,
-                            controller: info[:controller], app_file: info[:file] }
-            warnings.add("Shared file '#{relative}' uses app-dir symbol '#{sym}' " \
-                         "(from ux/app/#{info[:controller]}). " \
-                         "Move '#{sym}' to a shared dir or the shared file will be incomplete.")
-          end
+        content = shared_file_content[file_path]
+        next unless content
+
+        SymbolExtractor.extract_usages(content).each do |sym|
+          next unless controller_symbol_index.key?(sym)
+
+          info = controller_symbol_index[sym]
+          violations << { shared_file: relative, symbol: sym,
+                          controller: info[:controller], app_file: info[:file] }
+          warnings.add("Shared file '#{relative}' uses app-dir symbol '#{sym}' " \
+                       "(from ux/app/#{info[:controller]}). " \
+                       "Move '#{sym}' to a shared dir or the shared file will be incomplete.")
         end
       end
       violations
@@ -229,22 +224,15 @@ module ReactManifest
           next
         end
 
-        local_syms = Set.new
-        DEFINITION_PATTERNS.each { |p| content.scan(p) { |m| local_syms << m[0] } }
-
-        [PASCAL_TOKEN_PATTERN, HOOK_TOKEN_PATTERN].each do |pattern|
-          content.scan(pattern) do |match|
-            sym = match[0]
-            next if local_syms.include?(sym)
-            next unless controller_symbol_index.key?(sym)
-
-            info = controller_symbol_index[sym]
-            violations << { external_file: relative, symbol: sym,
-                            controller: info[:controller], app_file: info[:file] }
-            warnings.add("External file '#{relative}' uses app-dir symbol '#{sym}' " \
-                         "(from ux/app/#{info[:controller]}). " \
-                         "Move '#{sym}' into a shared ux dir to avoid duplicate runtime declarations.")
-          end
+        SymbolExtractor.extract_usages(content).each do |sym|
+          next unless controller_symbol_index.key?(sym)
+
+          info = controller_symbol_index[sym]
+          violations << { external_file: relative, symbol: sym,
+                          controller: info[:controller], app_file: info[:file] }
+          warnings.add("External file '#{relative}' uses app-dir symbol '#{sym}' " \
+                       "(from ux/app/#{info[:controller]}). " \
+                       "Move '#{sym}' into a shared ux dir to avoid duplicate runtime declarations.")
         end
       end
       violations
@@ -314,26 +302,6 @@ module ReactManifest
       used
     end
 
-    def scan_component_usage(content, pattern, symbol_index, used)
-      content.scan(pattern) do |match|
-        sym = match[0]
-        next unless symbol_index.key?(sym)
-
-        used << symbol_index[sym]
-      end
-    end
-
-    def scan_array_component_usage(content, symbol_index, used)
-      content.scan(ARRAY_COMPONENT_LIST_PATTERN) do |match|
-        list = match[0]
-        list.split(/\s*,\s*/).each do |sym|
-          next unless symbol_index.key?(sym)
-
-          used << symbol_index[sym]
-        end
-      end
-    end
-
     def abs_external_root(path)
       return path if Pathname.new(path).absolute?
 

data/lib/react_manifest/sprockets_manifest_patcher.rb

@@ -8,6 +8,8 @@ module ReactManifest
   # Usage:
   #   ReactManifest::SprocketsManifestPatcher.new(config).patch!
   class SprocketsManifestPatcher
+    include ReactManifest::Logging
+
     MANIFEST_GLOB = "app/assets/config/manifest.js".freeze
 
     Result = Struct.new(:file, :status, :detail, keyword_init: true)
@@ -37,13 +39,13 @@ module ReactManifest
       new_content = append_directive(content, directive)
 
       if @config.dry_run?
-        $stdout.puts "[ReactManifest] DRY-RUN: would patch #{short(path)}"
-        $stdout.puts "  + #{directive.strip}"
+        log_info "DRY-RUN: would patch #{short(path)}"
+        log_info "  + #{directive.strip}"
         return Result.new(file: path, status: :dry_run, detail: nil)
       end
 
       File.write(path, new_content, encoding: "utf-8")
-      $stdout.puts "[ReactManifest] Patched Sprockets manifest: #{short(path)}"
+      log_info "Patched Sprockets manifest: #{short(path)}"
       Result.new(file: path, status: :patched, detail: nil)
     end
 

data/lib/react_manifest/symbol_extractor.rb

@@ -0,0 +1,69 @@
+module ReactManifest
+  module SymbolExtractor
+    DEFINITION_PATTERNS = [
+      /(?:const|let|var)\s+([A-Z][A-Za-z0-9_]*)\s*=/,
+      /function\s+([A-Z][A-Za-z0-9_]*)\s*\(/,
+      /class\s+([A-Z][A-Za-z0-9_]*)\s*(?:extends|\{)/,
+      /(?:const|let|var)\s+(use[A-Z][A-Za-z0-9_]*)\s*=/,
+      /function\s+(use[A-Z][A-Za-z0-9_]*)\s*\(/,
+      /^export\s+default\s+(?:function|class)\s+([A-Z][A-Za-z0-9_]*)/,
+      /^export\s+default\s+(?:function|class)\s+(use[A-Z][A-Za-z0-9_]*)/,
+      /^export\s+(?:const|let|var)\s+([A-Z][A-Za-z0-9_]*)\s*=/,
+      /^export\s+(?:const|let|var)\s+(use[A-Z][A-Za-z0-9_]*)\s*=/,
+      /^export\s+function\s+([A-Z][A-Za-z0-9_]*)\s*\(/,
+      /^export\s+function\s+(use[A-Z][A-Za-z0-9_]*)\s*\(/,
+      /^export\s+class\s+([A-Z][A-Za-z0-9_]*)\s*(?:extends|\{)/
+    ].freeze
+
+    PASCAL_TOKEN_PATTERN = /\b([A-Z][A-Za-z0-9_]*)\b/
+    HOOK_TOKEN_PATTERN   = /\b(use[A-Z][A-Za-z0-9_]*)\b/
+    LIB_CALL_PATTERN     = /\b([a-z][A-Za-z0-9_]{2,})\s*\(/
+
+    JS_BUILTINS = %w[
+      require function return typeof instanceof delete void
+      console document window location history navigator
+      setTimeout setInterval clearTimeout clearInterval
+      parseInt parseFloat isNaN isFinite encodeURI decodeURI
+      fetch Promise Object Array String Number Boolean Math JSON
+      Object Array String Number Boolean Symbol Map Set WeakMap
+    ].freeze
+
+    module_function
+
+    def extract_definitions(content)
+      return [] unless content
+
+      symbols = []
+      DEFINITION_PATTERNS.each do |pattern|
+        content.scan(pattern) { |m| symbols << m[0] }
+      end
+      symbols.uniq
+    end
+
+    def extract_usages(content)
+      return [] unless content
+
+      local_syms = Set.new
+      DEFINITION_PATTERNS.each { |p| content.scan(p) { |m| local_syms << m[0] } }
+
+      used = []
+
+      content.scan(PASCAL_TOKEN_PATTERN) do |match|
+        sym = match[0]
+        used << sym unless local_syms.include?(sym)
+      end
+
+      content.scan(HOOK_TOKEN_PATTERN) do |match|
+        sym = match[0]
+        used << sym unless local_syms.include?(sym)
+      end
+
+      content.scan(LIB_CALL_PATTERN) do |match|
+        sym = match[0]
+        used << sym unless JS_BUILTINS.include?(sym) || local_syms.include?(sym)
+      end
+
+      used.uniq
+    end
+  end
+end

data/lib/react_manifest/tree_classifier.rb

@@ -5,6 +5,8 @@ module ReactManifest
   #
   # No hard-coded dir names — anything that is not app_dir is shared.
   class TreeClassifier
+    include ReactManifest::Logging
+
     Result = Struct.new(:controller_dirs, :shared_dirs, keyword_init: true)
 
     def initialize(config = ReactManifest.configuration)
@@ -16,8 +18,8 @@ module ReactManifest
       shared_dirs     = []
 
       unless Dir.exist?(@config.abs_ux_root)
-        warn "[ReactManifest] ux_root does not exist: #{@config.abs_ux_root}. " \
-             "Create the directory and run `rails react_manifest:generate`."
+        log_warn "ux_root does not exist: #{@config.abs_ux_root}. " \
+                 "Create the directory and run `rails react_manifest:generate`."
         return Result.new(controller_dirs: [], shared_dirs: [])
       end
 
@@ -40,7 +42,7 @@ module ReactManifest
                 }
               end
             rescue Errno::EACCES => e
-              warn "[ReactManifest] Permission denied reading #{full_path}: #{e.message}"
+              log_warn "Permission denied reading #{full_path}: #{e.message}"
             end
           else
             shared_dirs << {
@@ -50,7 +52,7 @@ module ReactManifest
           end
         end
       rescue Errno::EACCES => e
-        warn "[ReactManifest] Permission denied reading ux_root #{@config.abs_ux_root}: #{e.message}"
+        log_warn "Permission denied reading ux_root #{@config.abs_ux_root}: #{e.message}"
         return Result.new(controller_dirs: [], shared_dirs: [])
       end
 

data/lib/react_manifest/version.rb

@@ -1,3 +1,3 @@
 module ReactManifest
-  VERSION = "0.2.28".freeze
+  VERSION = "0.2.30".freeze
 end

data/lib/react_manifest/watcher.rb

@@ -7,27 +7,40 @@ module ReactManifest
   #
   # Watches ux_root recursively so newly added controller directories are
   # picked up without a server restart.
+  #
+  # File-change callbacks are debounced by the listen gem and handled on a
+  # background thread. Rapid back-to-back changes are coalesced: if a
+  # regeneration is already in progress when a new change arrives, only one
+  # additional regeneration is queued (not one per file event).
   module Watcher
     DEBOUNCE_SECONDS = 0.3
+    BRANCH_SWITCH_COOLDOWN = 3
 
     class << self
+      include ReactManifest::Logging
+
       def start(config = ReactManifest.configuration)
         begin
           require "listen"
         rescue LoadError
-          log "listen gem not available — file watching disabled. " \
-              "Add `gem 'listen'` to the development group in your Gemfile."
+          log_warn "listen gem not available — file watching disabled. " \
+                   "Add `gem 'listen'` to the development group in your Gemfile."
           return
         end
 
         root = config.abs_ux_root
 
         unless Dir.exist?(root)
-          log "ux_root does not exist (#{root}) — file watching disabled until directory is created."
+          log_warn "ux_root does not exist (#{root}) — file watching disabled until directory is created."
           return
         end
 
-        log "Watching #{root.sub("#{Rails.root}/", '')} for changes..."
+        @regen_mutex = Mutex.new
+        @git_dir = detect_git_dir
+        @last_git_head = read_git_head
+        @branch_switch_until = nil
+
+        log_info "Watching #{root.sub("#{Rails.root}/", '')} for changes..."
 
         @listener = Listen.to(
           root,
@@ -35,8 +48,8 @@ module ReactManifest
           latency: DEBOUNCE_SECONDS
         ) do |modified, added, removed|
           changed = (modified + added + removed).map { |f| File.basename(f) }
-          log "File change detected: #{changed.join(', ')}"
-          regenerate!(config)
+          log_info "File change detected: #{changed.join(', ')}"
+          handle_file_changes(modified, added, removed, config)
         end
 
         @listener.start
@@ -45,31 +58,114 @@ module ReactManifest
       def stop
         @listener&.stop
         @listener = nil
+        @regen_thread&.join(5)
+        @regen_thread = nil
       end
 
       def running?
         !@listener.nil?
       end
 
+      # Kill the background regen thread and reset all regen state.
+      # Intended for use in tests only.
+      def reset_regen_state!
+        thread = @regen_thread
+        if thread&.alive?
+          thread.kill
+          thread.join(1)
+        end
+        @regen_thread  = nil
+        @regen_pending = false
+        @regen_mutex   = nil
+        @git_dir       = nil
+        @last_git_head = nil
+        @branch_switch_until = nil
+      end
+
       private
 
-      def regenerate!(config)
-        Generator.new(config).run!
-        log "Manifests regenerated"
-      rescue StandardError => e
-        log "Error during regeneration: #{e.message}"
-        log e.backtrace.first(5).join("\n") if config.verbose?
+      def handle_file_changes(modified, added, removed, config)
+        if branch_switch_detected?
+          log_info "Branch change detected — skipping regeneration"
+          return
+        end
+
+        (modified + added + removed).each { |f| Scanner.invalidate(f) }
+        schedule_regeneration(config)
+      end
+
+      def branch_switch_detected?
+        return false unless @git_dir
+
+        return true if @branch_switch_until && Time.now < @branch_switch_until
+
+        current_head = read_git_head
+        return false unless current_head && @last_git_head
+
+        if current_head != @last_git_head
+          @last_git_head = current_head
+          @branch_switch_until = Time.now + BRANCH_SWITCH_COOLDOWN
+          return true
+        end
+
+        false
+      end
+
+      def detect_git_dir
+        git_path = File.join(Rails.root.to_s, ".git")
+        if File.file?(git_path)
+          content = File.read(git_path).strip
+          return content.sub("gitdir: ", "").strip if content.start_with?("gitdir: ")
+        elsif File.directory?(git_path)
+          return git_path
+        end
+        nil
+      rescue StandardError
+        nil
       end
 
-      def log(message)
-        msg = "[ReactManifest] #{message}"
-        if defined?(Rails) && Rails.logger
-          Rails.logger.info(msg)
-          $stdout.puts(msg) if Rails.env.development? && ReactManifest.configuration.stdout_logging?
-        else
-          $stdout.puts msg
+      def read_git_head
+        return nil unless @git_dir
+
+        File.read(File.join(@git_dir, "HEAD")).strip
+      rescue StandardError
+        nil
+      end
+
+      # Schedule a regeneration on the background thread. Coalesces rapid
+      # back-to-back file events: if the regen thread is already running,
+      # we just set @regen_pending and return immediately so the listen
+      # callback is never blocked.
+      def schedule_regeneration(config)
+        @regen_mutex ||= Mutex.new
+        mutex = @regen_mutex
+        mutex.synchronize do
+          @regen_pending = true
+          return if @regen_thread&.alive?
+
+          @regen_thread = Thread.new { regen_loop(config, mutex) }
         end
       end
+
+      # Background thread: regenerate, then check whether another change
+      # arrived while we were busy. If so, regenerate again; otherwise exit.
+      def regen_loop(config, mutex)
+        loop do
+          mutex.synchronize { @regen_pending = false }
+          regenerate!(config)
+          still_pending = mutex.synchronize { @regen_pending }
+          break unless still_pending
+        end
+      end
+
+      def regenerate!(config)
+        results = Generator.new(config).run!
+        written = results.count { |r| r[:status] == :written }
+        log_info "#{written} manifest(s) written" if written.positive?
+      rescue StandardError => e
+        log_warn "Error during regeneration: #{e.message}"
+        log_debug e.backtrace.first(5).join("\n") if config.verbose?
+      end
     end
   end
 end