react-manifest-rails 0.1.0

data/lib/react_manifest/generator.rb

@@ -0,0 +1,206 @@
+require "digest"
+require "set"
+require "time"
+require "tmpdir"
+
+module ReactManifest
+  # Generates all ux_*.js Sprockets manifest files.
+  #
+  # Generates:
+  #   ux_shared.js   — requires all files from shared dirs (components/, hooks/, lib/, etc.)
+  #   ux_<ctrl>.js   — one per controller subdir, requires ux_shared + controller files
+  #
+  # All generated files carry the AUTO-GENERATED header and are idempotent
+  # (skips write if content unchanged). Writes are atomic (temp-file + rename)
+  # to avoid partial reads from concurrent processes.
+  #
+  # Never touches application.js, application_dev.js, or files in exclude_paths.
+  class Generator
+    HEADER = <<~JS
+      // AUTO-GENERATED — DO NOT EDIT
+      // react-manifest-rails %<version>s | %<timestamp>s
+      // Run `rails react_manifest:generate` to regenerate.
+    JS
+
+    def initialize(config = ReactManifest.configuration)
+      @config     = config
+      @classifier = TreeClassifier.new(config)
+    end
+
+    # Run full generation. Returns array of {path:, status:} hashes.
+    def run!
+      results        = []
+      classification = @classifier.classify
+
+      # 1. Generate ux_shared.js
+      results << generate_shared(classification.shared_dirs)
+
+      # 2. Generate one ux_<controller>.js per controller dir
+      classification.controller_dirs.each do |ctrl|
+        results << generate_controller(ctrl)
+      end
+
+      print_summary(results) if @config.verbose?
+      results
+    end
+
+    private
+
+    # ------------------------------------------------------------------ shared
+
+    def generate_shared(shared_dirs)
+      lines     = header_lines
+      any_files = false
+
+      shared_dirs.each do |shared_dir|
+        files = js_files_in(shared_dir[:path])
+        next if files.empty?
+
+        any_files = true
+        files.each { |f| lines << "//= require #{relative_require_path(f)}" }
+      end
+
+      unless any_files
+        lines << "// (no shared files found)"
+      end
+
+      bundle_name = @config.shared_bundle
+      write_manifest("#{bundle_name}.js", lines.join("\n") + "\n")
+    end
+
+    # --------------------------------------------------------------- controller
+
+    def generate_controller(ctrl)
+      lines = header_lines
+      lines << "//= require #{@config.shared_bundle}"
+      lines << ""
+
+      files = js_files_in(ctrl[:path])
+      if files.empty?
+        lines << "// (no JSX files found in #{ctrl[:name]}/)"
+      else
+        files.each { |f| lines << "//= require #{relative_require_path(f)}" }
+      end
+
+      write_manifest("#{ctrl[:bundle_name]}.js", lines.join("\n") + "\n")
+    end
+
+    # --------------------------------------------------------------- write
+
+    def write_manifest(filename, content)
+      dest = File.join(@config.abs_output_dir, filename)
+
+      # Safety: never touch files not bearing our AUTO-GENERATED header
+      # (unless they don't exist yet)
+      if File.exist?(dest) && !auto_generated?(dest)
+        return { path: dest, status: :skipped_pinned }
+      end
+
+      new_digest = Digest::SHA256.hexdigest(content)
+
+      if File.exist?(dest)
+        existing_digest = Digest::SHA256.hexdigest(File.read(dest, encoding: "utf-8"))
+        if existing_digest == new_digest
+          return { path: dest, status: :unchanged }
+        end
+      end
+
+      if @config.dry_run?
+        $stdout.puts "[ReactManifest] DRY-RUN: would write #{dest}"
+        print_diff(dest, content)
+        return { path: dest, status: :dry_run }
+      end
+
+      FileUtils.mkdir_p(File.dirname(dest))
+
+      # Atomic write: write to a temp file in the same directory then rename,
+      # so concurrent readers never see a partially-written manifest.
+      tmp = "#{dest}.tmp.#{Process.pid}"
+      begin
+        File.write(tmp, content, encoding: "utf-8")
+        File.rename(tmp, dest)
+      rescue => e
+        File.unlink(tmp) if File.exist?(tmp)
+        raise e
+      end
+
+      { path: dest, status: :written }
+    end
+
+    # ----------------------------------------------------------- helpers
+
+    def header_lines
+      [
+        HEADER % { version: ReactManifest::VERSION, timestamp: Time.now.utc.iso8601 },
+        ""
+      ].flatten
+    end
+
+    def js_files_in(dir)
+      return [] unless Dir.exist?(dir)
+
+      files = Dir.glob(File.join(dir, "**", "*.{js,jsx}"))
+        .reject { |f| File.directory?(f) }
+        .reject { |f| auto_generated?(f) }
+        .reject { |f| excluded_path?(f) }
+        .sort
+
+      # Deduplicate by logical require path: if both foo.js and foo.jsx exist,
+      # keep foo.js (sorted first) to avoid duplicate //= require directives
+      # that would cause a Sprockets error.
+      seen = Set.new
+      files.each_with_object([]) do |f, uniq|
+        logical = relative_require_path(f)
+        next if seen.include?(logical)
+        seen << logical
+        uniq << f
+      end
+    end
+
+    # Returns true if the file path contains a component matching any exclude_path.
+    # exclude_paths are matched against individual path segments, so "vendor" matches
+    # ux/vendor/foo.js but not ux/vendor_custom/foo.js.
+    def excluded_path?(abs_path)
+      parts = abs_path.split(File::SEPARATOR)
+      @config.exclude_paths.any? { |ep| parts.include?(ep) }
+    end
+
+    def relative_require_path(abs_path)
+      # 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 → ""
+      rel.sub(/\.js\.jsx$/, "").sub(/\.jsx$/, "").sub(/\.js$/, "")
+    end
+
+    def auto_generated?(path)
+      return false unless File.exist?(path)
+      # Read up to first 2 lines — handles empty files (first.to_s returns "")
+      # without incorrectly treating them as user-pinned.
+      first_two = File.foreach(path).first(2).join
+      first_two.include?("AUTO-GENERATED")
+    end
+
+    def print_diff(dest, new_content)
+      if File.exist?(dest)
+        old_lines = File.readlines(dest, encoding: "utf-8")
+        new_lines = new_content.lines
+
+        removed = old_lines - new_lines
+        added   = new_lines - old_lines
+
+        removed.each { |l| $stdout.puts "  - #{l.chomp}" }
+        added.each   { |l| $stdout.puts "  + #{l.chomp}" }
+      else
+        new_content.each_line { |l| $stdout.puts "  + #{l.chomp}" }
+      end
+    end
+
+    def print_summary(results)
+      counts = results.group_by { |r| r[:status] }.transform_values(&:count)
+      $stdout.puts "[ReactManifest] Generated: #{counts[:written] || 0} written, " \
+                   "#{counts[:unchanged] || 0} unchanged, " \
+                   "#{counts[:skipped_pinned] || 0} skipped (not auto-generated)"
+    end
+  end
+end

data/lib/react_manifest/railtie.rb

@@ -0,0 +1,46 @@
+require "rails/railtie"
+
+module ReactManifest
+  class Railtie < Rails::Railtie
+    # Expose config as Rails.application.config.react_manifest
+    config.react_manifest = ReactManifest.configuration
+
+    # ----------------------------------------------------------------
+    # Start the file watcher in development
+    # ----------------------------------------------------------------
+    initializer "react_manifest.start_watcher" do
+      if Rails.env.development? && !ReactManifest::Watcher.running?
+        begin
+          ReactManifest::Watcher.start(ReactManifest.configuration)
+        rescue => e
+          Rails.logger.warn "[ReactManifest] Could not start file watcher: #{e.message}"
+        end
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Include react_bundle_tag in all ActionView templates
+    # ----------------------------------------------------------------
+    initializer "react_manifest.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include ReactManifest::ViewHelpers
+      end
+    end
+
+    # ----------------------------------------------------------------
+    # Hook manifest generation into assets:precompile
+    # (safety net for CI/production — dev uses the watcher)
+    #
+    # Using prepend_actions so generation runs as a block before
+    # Sprockets begins compiling, rather than as a Rake prerequisite
+    # (which is subject to parallel task ordering under rake -j).
+    # ----------------------------------------------------------------
+    rake_tasks do
+      load File.expand_path("../../../tasks/react_manifest.rake", __FILE__)
+
+      if Rake::Task.task_defined?("assets:precompile")
+        Rake::Task["assets:precompile"].enhance(["react_manifest:generate"])
+      end
+    end
+  end
+end

data/lib/react_manifest/reporter.rb

@@ -0,0 +1,96 @@
+require "json"
+require "zlib"
+
+module ReactManifest
+  # Reports per-bundle sizes by reading the Sprockets compiled manifest.
+  #
+  # Run after `rails assets:precompile` to see:
+  #   Bundle                  Raw (KB)   Gzip (KB)
+  #   ux_shared.js              420         130
+  #   ux_notifications.js        95          31  ✓
+  #   ux_reports.js             610         190  ⚠
+  class Reporter
+    def initialize(config = ReactManifest.configuration)
+      @config = config
+    end
+
+    def report
+      manifest = load_sprockets_manifest
+      bundles  = collect_bundles(manifest)
+
+      if bundles.empty?
+        puts "[ReactManifest] No ux_*.js bundles found in compiled assets."
+        puts "  Run `rails assets:precompile` first."
+        return
+      end
+
+      print_table(bundles)
+    end
+
+    private
+
+    def load_sprockets_manifest
+      # Use Rails.public_path to respect non-default public directory config.
+      public_assets = Rails.public_path.join("assets")
+      manifest_file = Dir.glob(File.join(public_assets, ".sprockets-manifest-*.json")).first ||
+                      Dir.glob(File.join(public_assets, "manifest-*.json")).first
+
+      unless manifest_file && File.exist?(manifest_file)
+        puts "[ReactManifest] Sprockets manifest not found under #{public_assets}."
+        puts "  Run `rails assets:precompile` first."
+        return {}
+      end
+
+      JSON.parse(File.read(manifest_file, encoding: "utf-8"))["assets"] || {}
+    rescue JSON::ParserError => e
+      puts "[ReactManifest] Could not parse Sprockets manifest: #{e.message}"
+      {}
+    end
+
+    def collect_bundles(manifest)
+      public_assets = Rails.public_path.join("assets").to_s
+      bundles = []
+
+      manifest.each do |logical_path, fingerprinted|
+        next unless logical_path.match?(/\Aux_.*\.js\z/)
+
+        abs_path  = File.join(public_assets, fingerprinted)
+        gz_path   = "#{abs_path}.gz"
+
+        next unless File.exist?(abs_path)
+
+        raw_kb  = (File.size(abs_path) / 1024.0).round(1)
+        gzip_kb = File.exist?(gz_path) ? (File.size(gz_path) / 1024.0).round(1) : nil
+
+        bundles << {
+          name:    logical_path,
+          raw_kb:  raw_kb,
+          gzip_kb: gzip_kb
+        }
+      end
+
+      bundles.sort_by { |b| b[:name] }
+    end
+
+    def print_table(bundles)
+      gzip_available = bundles.any? { |b| b[:gzip_kb] }
+
+      puts "\n#{"Bundle".ljust(35)} #{"Raw (KB)".rjust(10)}#{gzip_available ? "   #{"Gzip (KB)".rjust(10)}" : ""}"
+      puts "-" * (gzip_available ? 62 : 48)
+
+      bundles.each do |b|
+        over_threshold = @config.size_threshold_kb > 0 && b[:raw_kb] > @config.size_threshold_kb
+        flag           = over_threshold ? "  ⚠ exceeds #{@config.size_threshold_kb}KB threshold" : ""
+        gzip_col       = gzip_available ? "   #{(b[:gzip_kb] || "n/a").to_s.rjust(10)}" : ""
+
+        puts "#{b[:name].ljust(35)} #{b[:raw_kb].to_s.rjust(10)}#{gzip_col}#{flag}"
+      end
+
+      unless gzip_available
+        puts "\n  Note: gzip sizes unavailable. Ensure `config.assets.compress = true` in production."
+      end
+
+      puts "\n"
+    end
+  end
+end

data/lib/react_manifest/scanner.rb

@@ -0,0 +1,192 @@
+require "set"
+
+module ReactManifest
+  # Scans JSX/JS files using regex (no AST, no Node.js required).
+  #
+  # Phase 1 — builds a symbol index from shared dirs:
+  #   "PrimaryButton" => "ux/components/buttons/primary_button"
+  #   "useFetch"      => "ux/hooks/use_fetch"
+  #   "formatDate"    => "ux/lib/format_date"
+  #
+  # Phase 2 — scans controller files for usage of those symbols
+  #   and produces per-controller lists of referenced shared files.
+  #
+  # Phase 3 — emits non-fatal warnings.
+  class Scanner
+    # Patterns to detect symbol definitions (no import/export in this codebase)
+    DEFINITION_PATTERNS = [
+      /(?: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(
+      /(?:const|let|var)\s+([a-z][A-Za-z0-9_]{2,})\s*=\s*(?:function|\()/,  # const formatDate = function/arrow
+      /^function\s+([a-z][A-Za-z0-9_]{2,})\s*\(/,            # function formatDate( at line start
+    ].freeze
+
+    # Patterns to detect usage in controller files
+    JSX_ELEMENT_PATTERN      = /<([A-Z][A-Za-z0-9_]*)[\s\/>]/.freeze
+    REACT_CREATE_PATTERN     = /React\.createElement\(\s*([A-Z][A-Za-z0-9_]*)[\s,)]/.freeze
+    HOOK_CALL_PATTERN        = /\b(use[A-Z][A-Za-z0-9_]*)\s*\(/.freeze
+    # Lib calls matched against known lib symbols to reduce false positives
+    LIB_CALL_PATTERN         = /\b([a-z][A-Za-z0-9_]{2,})\s*\(/.freeze
+
+    # 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
+
+    Result = Struct.new(:symbol_index, :controller_usages, :warnings, keyword_init: true)
+
+    def initialize(config = ReactManifest.configuration)
+      @config = config
+    end
+
+    def scan(classification)
+      warnings      = []
+      symbol_index  = {}
+
+      # Phase 1: index symbols from shared dirs
+      classification.shared_dirs.each do |shared_dir|
+        js_files_in(shared_dir[:path]).each do |file_path|
+          relative = relative_require_path(file_path)
+          symbols  = extract_definitions(file_path)
+          symbols.each do |sym|
+            if symbol_index.key?(sym)
+              warnings << "Duplicate symbol '#{sym}' in #{relative} (already from #{symbol_index[sym]})"
+            else
+              symbol_index[sym] = relative
+            end
+          end
+        end
+      end
+
+      if @config.verbose?
+        $stdout.puts "[ReactManifest] Shared symbol index: #{symbol_index.size} symbols indexed"
+      end
+
+      # Phase 2: scan controller dirs for usage
+      controller_usages = {}
+
+      classification.controller_dirs.each do |ctrl|
+        files   = js_files_in(ctrl[:path])
+        used    = Set.new
+
+        if files.empty? && @config.verbose?
+          warnings << "Controller dir '#{ctrl[:name]}' has no JS/JSX files"
+        end
+
+        files.each do |file_path|
+          validate_naming(file_path, ctrl[:name], warnings)
+          content = File.read(file_path, encoding: "utf-8")
+
+          # JSX element usage: <PrimaryButton (JSX tag syntax)
+          content.scan(JSX_ELEMENT_PATTERN) do |match|
+            sym = match[0]
+            if symbol_index.key?(sym)
+              used << symbol_index[sym]
+            end
+          end
+
+          # React.createElement(PrimaryButton, ...) (non-JSX style)
+          content.scan(REACT_CREATE_PATTERN) do |match|
+            sym = match[0]
+            if symbol_index.key?(sym)
+              used << symbol_index[sym]
+            end
+          end
+
+          # Hook calls: useFetch(
+          content.scan(HOOK_CALL_PATTERN) do |match|
+            sym = match[0]
+            if symbol_index.key?(sym)
+              used << symbol_index[sym]
+            end
+          end
+
+          # Lib function calls: formatDate( — filtered against lib symbol index
+          content.scan(LIB_CALL_PATTERN) do |match|
+            sym = match[0]
+            next if JS_BUILTINS.include?(sym)
+            if symbol_index.key?(sym)
+              used << symbol_index[sym]
+            end
+          end
+        end
+
+        controller_usages[ctrl[:name]] = used.to_a.sort
+      end
+
+      # Phase 3: additional warnings
+      emit_fanout_warnings(controller_usages, warnings)
+
+      Result.new(
+        symbol_index:       symbol_index,
+        controller_usages:  controller_usages,
+        warnings:           warnings
+      )
+    end
+
+    private
+
+    def js_files_in(dir)
+      return [] unless Dir.exist?(dir)
+      Dir.glob(File.join(dir, "**", "*.{js,js.jsx}"))
+        .reject { |f| File.directory?(f) }
+        .reject { |f| 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) }
+    end
+
+    def extract_definitions(file_path)
+      content = File.read(file_path, encoding: "utf-8")
+      symbols = []
+      DEFINITION_PATTERNS.each do |pattern|
+        content.scan(pattern) { |m| symbols << m[0] }
+      end
+      symbols.uniq
+    end
+
+    def relative_require_path(abs_path)
+      # 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 → ""
+      rel.sub(/\.js\.jsx$/, "").sub(/\.jsx$/, "").sub(/\.js$/, "")
+    end
+
+    def validate_naming(file_path, ctrl_name, warnings)
+      basename = File.basename(file_path, ".*").sub(/\.js$/, "")
+      # Expected: <controller>_index, <controller>_show, <controller>_form, etc.
+      unless basename.start_with?("#{ctrl_name}_") || basename == ctrl_name
+        warnings << "File '#{File.basename(file_path)}' in '#{ctrl_name}' does not follow " \
+                    "'#{ctrl_name}_<action>.js.jsx' naming convention"
+      end
+    end
+
+    def emit_fanout_warnings(controller_usages, warnings)
+      # Count how many controllers use each shared file
+      fanout = Hash.new(0)
+      controller_usages.each_value do |files|
+        files.each { |f| fanout[f] += 1 }
+      end
+
+      fanout.each do |file, count|
+        if count > 3
+          warnings << "High fan-out: '#{file}' is used by #{count} controllers " \
+                      "(consider ensuring it's in the shared bundle)"
+        end
+      end
+    end
+  end
+end

data/lib/react_manifest/tree_classifier.rb

@@ -0,0 +1,69 @@
+module ReactManifest
+  # Walks the ux/ directory tree and classifies subdirectories into:
+  #   - controller_dirs: immediate subdirs of ux/app/ (each gets a ux_<name>.js)
+  #   - shared_dirs:     everything else directly under ux/ (feeds ux_shared.js)
+  #
+  # No hard-coded dir names — anything that is not app_dir is shared.
+  class TreeClassifier
+    Result = Struct.new(:controller_dirs, :shared_dirs, keyword_init: true)
+
+    def initialize(config = ReactManifest.configuration)
+      @config = config
+    end
+
+    def classify
+      controller_dirs = []
+      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`."
+        return Result.new(controller_dirs: [], shared_dirs: [])
+      end
+
+      begin
+        Dir.children(@config.abs_ux_root).sort.each do |entry|
+          full_path = File.join(@config.abs_ux_root, entry)
+          next unless File.directory?(full_path)
+
+          if entry == @config.app_dir
+            begin
+              Dir.children(full_path).sort.each do |ctrl_entry|
+                ctrl_path = File.join(full_path, ctrl_entry)
+                next unless File.directory?(ctrl_path)
+                next if @config.ignore.include?(ctrl_entry)
+
+                controller_dirs << {
+                  name:        ctrl_entry,
+                  path:        ctrl_path,
+                  bundle_name: "ux_#{ctrl_entry}"
+                }
+              end
+            rescue Errno::EACCES => e
+              warn "[ReactManifest] Permission denied reading #{full_path}: #{e.message}"
+            end
+          else
+            shared_dirs << {
+              name: entry,
+              path: full_path
+            }
+          end
+        end
+      rescue Errno::EACCES => e
+        warn "[ReactManifest] Permission denied reading ux_root #{@config.abs_ux_root}: #{e.message}"
+        return Result.new(controller_dirs: [], shared_dirs: [])
+      end
+
+      Result.new(controller_dirs: controller_dirs, shared_dirs: shared_dirs)
+    end
+
+    # Watch ux_root recursively so newly added controller directories
+    # are automatically detected without restarting the development server.
+    def watched_dirs
+      return [] unless Dir.exist?(@config.abs_ux_root)
+      dirs = [@config.abs_ux_root]
+      dirs << @config.abs_app_dir if Dir.exist?(@config.abs_app_dir)
+      dirs
+    end
+  end
+end

data/lib/react_manifest/version.rb

@@ -0,0 +1,3 @@
+module ReactManifest
+  VERSION = "0.1.0"
+end

data/lib/react_manifest/view_helpers.rb

@@ -0,0 +1,27 @@
+module ReactManifest
+  # Provides the `react_bundle_tag` view helper, included in ActionView::Base.
+  #
+  # Usage in layouts:
+  #   <%= react_bundle_tag defer: true %>
+  #
+  # Resolves which ux_*.js bundles to include based on controller_path:
+  #   1. Always includes config.shared_bundle (e.g. "ux_shared")
+  #   2. Always appends config.always_include (e.g. ["ux_main"])
+  #   3. Appends "ux_<controller_path>" if that bundle file exists
+  #   4. For namespaced controllers (admin/users): checks ux_admin_users, then ux_admin
+  #   5. Returns "" for pure ERB/HAML pages with no matching bundle, or when
+  #      called outside a controller context (mailers, engines, etc.)
+  module ViewHelpers
+    def react_bundle_tag(**html_options)
+      # controller_path is not available in all view contexts (mailers, engines,
+      # views rendered outside a request). Fall back gracefully rather than raising.
+      ctrl = respond_to?(:controller_path, true) ? controller_path : nil
+      return "".html_safe if ctrl.nil?
+
+      bundles = ReactManifest.resolve_bundles(ctrl)
+      return "".html_safe if bundles.empty?
+
+      javascript_include_tag(*bundles, **html_options)
+    end
+  end
+end