react-manifest-rails 0.2.34 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0076f3ffaf1c303d4ac14a8345477b3851045267b0cba8f823f49ce5f17efa4f
-  data.tar.gz: 579d04e786fe515e46d9c56c5c755efcf616cfd49289fcef8ccda0cc4cce7fa8
+  metadata.gz: 42ca130740decc2c19123ab8e2d0b368925f0bd988736d84a9087d4016e1836c
+  data.tar.gz: e9e23a7c0eb8dea12f4eb8498f08bff0ea11fe56f168833ae3ef13e090b4d59a
 SHA512:
-  metadata.gz: 6d221314836bc176da1378824e2ab7a55232d5977db2ca46b353d98f499b8e49d31b7999d0787953944db9c8b1c8652f3f17422918ee59d0fd5b78f5d46dca65
-  data.tar.gz: 3eeaba00d80ad2e7c73b1320026ea4b3ed0ed989b5a3c33513a2e45f6e63f7b632b466c2cb192e163b42892f4bce76b2dc59b87b90d90869c4eaa5137f4a8a86
+  metadata.gz: d73c047a2257f229e26682658c2644c0645fd362ba30f2f2ef34fceb15ecf83cf282b2c7899472e3eb25351b30512b5a3e8dbe456e1057502453876f2ce1868d
+  data.tar.gz: 78ebfd5b3390fa6204d6a59a46d94f1aef87c87359b499049f745da68d493f2dab3dd4fefe1f46667ca1be40f66c02e17fa1b977f3fc5b67370a9ba37a9b0566

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-15
+
+### Fixed
+- `always_include` no longer double-declares. Its bundles are delivered on every page
+  by their own `<script>` tag (both `react_bundle_tag`/`resolve_bundles` and
+  `react_component` now emit them), and their files are no longer inlined into each
+  controller manifest. Previously the separate tag plus the inline loaded an
+  always_include bundle's **private** files twice on any other controller's page, and a
+  **collided** symbol whose definer lives in an always_include bundle could pull a
+  second definer into the consumer — both causing "Identifier X has already been
+  declared". Controller dependency resolution now treats symbols provided by an
+  always_include bundle as already satisfied, and skips those bundles when inlining
+  dependencies (legacy `auto_shared = false` path included). The "already provided"
+  set is computed from the exact files the always_include `<script>` tag actually
+  carries (its own non-promoted files plus the canonical dependency files it inlines),
+  not from whole dependency bundles — so a consumer never drops a definer for a symbol
+  that lives in a sibling file the tag does not load. Symbol availability that the
+  previous inlining protected (added in 0.2.24) is preserved by the tag `react_component`
+  now emits.
+- One case remains inherently unresolvable by dependency arithmetic: when an
+  `always_include` bundle *consumes* a collided symbol, its tag inlines the
+  first-writer definer, which also lives in that definer's own bundle manifest, so on
+  the definer's own page the file loads twice. `react_manifest:generate` now emits a
+  warning naming the always_include bundle, the duplicated file/symbol, and the owning
+  bundle, with the fix (rename or relocate the collided symbol). Detected in both the
+  default and legacy (`auto_shared = false`) modes.
+
+### Added
+- Auto-promotion: a component defined under `ux/app/<controller>/` but used by any
+  other bundle is now emitted into `ux_shared` (loaded once per page) instead of being
+  inlined into each consumer. This eliminates duplicate top-level `const` declarations
+  ("Identifier X has already been declared") — and the cascading `X is not defined`
+  errors that follow when a SyntaxError aborts a concatenated bundle — for components
+  shared across controllers (e.g. a navbar component pulled in via `always_include`).
+  Files never move; only the `//= require` line's destination changes. Promotion is
+  transitive. `react_manifest:analyze` now lists what was promoted and why. Set
+  `config.auto_shared = false` to restore the previous inline behavior.
+
+### Changed
+- Generated `ux_manifests/*.js` are now treated as build artifacts. `react_manifest:setup`
+  and the development boot step add them to `.gitignore` (idempotently) and keep a
+  committed `.keep` so the directory always exists; setup prints a one-time
+  `git rm --cached` to untrack previously-committed manifests. Production is unaffected
+  (manifests regenerate during `assets:precompile`). Opt out with
+  `config.manage_gitignore = false`. Upgrading an existing app requires no manual step:
+  the first dev boot regenerates manifests and ensures the ignore entry.
+
 ## [0.2.34] - 2026-07-02
 
 ### Added

data/lib/react_manifest/configuration.rb

@@ -21,9 +21,18 @@ module ReactManifest
     # Keeping generated files out of output_dir root avoids clutter.
     attr_accessor :manifest_subdir
 
+    # When true (default), the gem ensures the generated manifest dir is gitignored
+    # (adds the entry on dev boot if missing). Set false to manage .gitignore yourself.
+    attr_accessor :manage_gitignore
+
     # Bundle name for auto-generated shared bundle (all non-app/ dirs)
     attr_accessor :shared_bundle
 
+    # When true (default), a component defined under app_dir but used by any other
+    # bundle is emitted into the shared bundle (loaded once per page) instead of
+    # being inlined into each consumer. Set false to restore legacy inlining.
+    attr_accessor :auto_shared
+
     # Bundles always prepended by react_bundle_tag (e.g. ["ux_main"])
     attr_accessor :always_include
 
@@ -101,7 +110,9 @@ module ReactManifest
       @app_dir           = "app"
       @output_dir        = "app/assets/javascripts"
       @manifest_subdir   = "ux_manifests"
+      @manage_gitignore  = true
       @shared_bundle     = "ux_shared"
+      @auto_shared       = true
       @always_include    = []
       @ignore            = []
       @isolated_app_dirs = []
@@ -119,6 +130,10 @@ module ReactManifest
       !!@dry_run
     end
 
+    def auto_shared?
+      !!@auto_shared
+    end
+
     def verbose?
       !!@verbose
     end
@@ -127,6 +142,10 @@ module ReactManifest
       !!@stdout_logging
     end
 
+    def manage_gitignore?
+      !!@manage_gitignore
+    end
+
     # Glob fragment used by Dir.glob, e.g. "*.{js,jsx}" or "*.{js,jsx,ts,tsx}"
     def extensions_glob
       "*.{#{extensions.join(',')}}"

data/lib/react_manifest/generator.rb

@@ -42,6 +42,14 @@ module ReactManifest
       @classifier = TreeClassifier.new(config)
     end
 
+    # After a run (or on demand), maps a promoted file's require path to the set of
+    # bundle names that forced its promotion. Used by react_manifest:analyze.
+    def promotion_reasons
+      classification = @classifier.classify
+      build_controller_context(classification.controller_dirs, classification.shared_dirs)
+      @promotion_reasons || {}
+    end
+
     # Run full generation. Returns array of {path:, status:} hashes.
     #
     # All manifest content is built first (no filesystem writes), then written
@@ -49,10 +57,10 @@ module ReactManifest
     # written and others stale/missing.
     def run!
       classification = @classifier.classify
-      controller_context = build_controller_context(classification.controller_dirs)
+      controller_context = build_controller_context(classification.controller_dirs, classification.shared_dirs)
 
       # Phase 1: build all content in memory — no I/O.
-      shared_manifest = build_shared(classification.shared_dirs)
+      shared_manifest = build_shared(classification.shared_dirs, controller_context[:promoted_files])
       manifests = [shared_manifest] + classification.controller_dirs.map do |ctrl|
         build_controller(ctrl, controller_context)
       end
@@ -98,10 +106,9 @@ module ReactManifest
 
     # ------------------------------------------------------------------ shared
 
-    def build_shared(shared_dirs)
+    def build_shared(shared_dirs, promoted_files = Set.new)
       lines = header_lines
-      reqs = shared_dirs
-             .flat_map { |d| js_files_in(d[:path]) }
+      reqs = (shared_dirs.flat_map { |d| js_files_in(d[:path]) } + promoted_files.to_a)
              .map { |f| normalize_require_path(relative_require_path(f)) }
              .uniq
              .sort
@@ -119,13 +126,21 @@ module ReactManifest
 
     def build_controller(ctrl, controller_context)
       lines = header_lines
-      always_include_reqs = controller_context[:always_include_requires].fetch(ctrl[:bundle_name], [])
-      dep_requires = controller_dependency_requires(ctrl[:bundle_name], controller_context)
-      ext_reqs = controller_context[:external_requires].fetch(ctrl[:bundle_name], Set.new).to_a.sort
-
-      files = js_files_in(ctrl[:path])
+      promoted = controller_context[:promoted_files]
+      bundle_name = ctrl[:bundle_name]
+      # always_include bundles are NOT inlined here: resolve_bundles /
+      # react_component deliver them on every page via their own <script> tag,
+      # so inlining would load the same file twice and double-declare.
+      dep_requires = if @config.auto_shared?
+                       promoted_aware_dependency_requires(bundle_name, controller_context)
+                     else
+                       controller_dependency_requires(bundle_name, controller_context)
+                     end
+      ext_reqs = controller_context[:external_requires].fetch(bundle_name, Set.new).to_a.sort
+
+      files = js_files_in(ctrl[:path]).reject { |f| promoted.include?(f) }
       own_requires = files.map { |f| relative_require_path(f) }
-      all_requires = (always_include_reqs + dep_requires + ext_reqs + own_requires).uniq
+      all_requires = (dep_requires + ext_reqs + own_requires).uniq
 
       if all_requires.empty?
         lines << "// (no JSX files found in #{ctrl[:name]}/)"
@@ -136,66 +151,303 @@ module ReactManifest
       { filename: "#{ctrl[:bundle_name]}.js", content: "#{lines.join("\n")}\n" }
     end
 
-    def build_controller_context(controller_dirs)
+    def build_controller_context(controller_dirs, shared_dirs)
+      bundle_files, file_owner, file_defs, symbol_to_bundle, symbol_to_file,
+      symbol_definers, bundle_own_symbols = index_controller_symbols(controller_dirs)
+
+      file_uses = Hash.new { |h, k| h[k] = Set.new }
+      symbol_used_by_bundles = Hash.new { |h, k| h[k] = Set.new }
+      record_symbol_usages(bundle_files, shared_dirs, file_uses, symbol_used_by_bundles)
+
+      collided = symbol_definers.each_with_object(Set.new) do |(sym, files), acc|
+        acc << sym if files.size >= 2
+      end
+
+      external_symbol_to_require = index_external_symbols(symbol_to_bundle)
+
+      dependencies, external_requires = build_dependency_graph(
+        bundle_files, bundle_own_symbols, file_uses, symbol_to_bundle, external_symbol_to_require
+      )
+
+      symbol_index = {
+        file_defs: file_defs,
+        symbol_to_file: symbol_to_file,
+        symbol_used_by_bundles: symbol_used_by_bundles
+      }
+      promoted_files =
+        if @config.auto_shared?
+          compute_promoted_files(file_owner, file_uses, symbol_index, collided)
+        else
+          Set.new
+        end
+
+      context = {
+        bundle_files: bundle_files,
+        dependencies: dependencies,
+        external_requires: external_requires,
+        promoted_files: promoted_files,
+        file_uses: file_uses,
+        symbol_to_file: symbol_to_file,
+        bundle_own_symbols: bundle_own_symbols
+      }
+
+      # Bundles guaranteed loaded on every page by always_include (used to exclude
+      # them from the legacy whole-bundle inline path and to self-exclude an
+      # always_include bundle's own manifest from the skip below).
+      context[:always_loaded_bundles] = compute_always_loaded_bundles(dependencies)
+      # Symbols actually delivered on every page by the always_include <script>
+      # tag(s) — derived from the real files those tags carry, NOT from whole dep
+      # bundles (which would over-claim symbols the tag does not load and cause a
+      # consumer to skip a definer it still needs). Unused by the legacy path.
+      context[:always_provided_symbols] =
+        @config.auto_shared? ? compute_always_provided_symbols(context, file_defs) : Set.new
+
+      warn_on_always_include_collisions(context, file_owner, file_defs, collided)
+
+      context
+    end
+
+    # Surface the one case dependency arithmetic cannot resolve: an always_include
+    # bundle that CONSUMES a collided symbol. Its tag inlines the first-writer
+    # definer file, which also lives in that file's own bundle manifest — so on the
+    # definer's own page the file loads twice (once via the always_include tag,
+    # once via the owning bundle), a duplicate declaration. We cannot auto-fix it
+    # (there is no collision-free page-global home for a collided symbol), so we
+    # warn with the actionable fix: rename or relocate the symbol.
+    def warn_on_always_include_collisions(context, file_owner, file_defs, collided)
+      return if collided.empty?
+
+      bundles = @config.always_include.map(&:to_s).reject(&:empty?).uniq
+      bundles.each do |always_bundle|
+        always_include_foreign_files(always_bundle, context).each do |file|
+          owner = file_owner[file]
+          next if owner.nil? || owner == always_bundle
+
+          collided_syms = (file_defs.fetch(file, Set.new) & collided).to_a.sort
+          next if collided_syms.empty?
+
+          plural = collided_syms.size > 1 ? "s" : ""
+          log_warn "always_include bundle '#{always_bundle}' pulls in " \
+                   "'#{relative_require_path(file)}' (defines collided symbol#{plural} " \
+                   "#{collided_syms.join(', ')}) owned by '#{owner}'. On #{owner}'s own page " \
+                   "that file loads twice — once via the #{always_bundle} tag and once via " \
+                   "#{owner} — causing a duplicate declaration. Rename the symbol or move it " \
+                   "to a uniquely-named shared component."
+        end
+      end
+    end
+
+    # Files an always_include bundle's tag delivers from OTHER bundles: under
+    # auto_shared, the exact non-promoted dependency files it inlines; in legacy
+    # mode, every file of the dependency bundles it inlines wholesale.
+    def always_include_foreign_files(always_bundle, context)
+      if @config.auto_shared?
+        promoted_aware_dependency_files(always_bundle, context, Set.new)
+      else
+        transitive_dependencies(always_bundle, context[:dependencies])
+          .flat_map { |dep| context[:bundle_files].fetch(dep, []) }
+      end
+    end
+
+    # Symbols the always_include tag(s) put on every page: for each always_include
+    # bundle, the symbols defined by its own non-promoted files plus the canonical
+    # dependency files it inlines (its manifest's exact file closure).
+    def compute_always_provided_symbols(context, file_defs)
+      bundles = @config.always_include.map(&:to_s).reject(&:empty?).uniq
+      return Set.new if bundles.empty?
+
+      always_files = Set.new
+      bundles.each do |b|
+        context[:bundle_files].fetch(b, []).each do |file|
+          always_files << file unless context[:promoted_files].include?(file)
+        end
+        promoted_aware_dependency_files(b, context, Set.new).each { |file| always_files << file }
+      end
+
+      always_files.each_with_object(Set.new) { |file, syms| syms.merge(file_defs.fetch(file, Set.new)) }
+    end
+
+    # Files that can never be promoted to ux_shared: any file defining a "collided"
+    # symbol (a name with 2+ app-dir definers — promoting one copy into the always-
+    # loaded shared bundle would double-declare against the other copy on its page),
+    # plus any file that transitively depends on such a file (it can't live in shared
+    # if a dependency can't). These fall back to legacy per-consumer inlining.
+    def unpromotable_files(file_owner, file_defs, file_uses, symbol_to_file, collided)
+      unpromotable = Set.new
+      file_owner.each_key do |file_path|
+        unpromotable << file_path if file_defs[file_path].any? { |s| collided.include?(s) }
+      end
+
+      loop do
+        added = false
+        file_owner.each_key do |file_path|
+          next if unpromotable.include?(file_path)
+
+          taints = file_uses.fetch(file_path, Set.new).any? do |sym|
+            dep = symbol_to_file[sym]
+            dep && unpromotable.include?(dep)
+          end
+          if taints
+            unpromotable << file_path
+            added = true
+          end
+        end
+        break unless added
+      end
+
+      unpromotable
+    end
+
+    # A controller file is promoted to the shared bundle when a symbol it canonically
+    # defines is used by a bundle other than its owner, then transitively for anything
+    # a promoted file depends on. Collided/tainted files (see unpromotable_files) are
+    # never promoted. Records why each file was promoted for react_manifest:analyze.
+    #
+    # symbol_index bundles {file_defs:, symbol_to_file:, symbol_used_by_bundles:} into
+    # one param so this stays under Metrics/ParameterLists (rubocop flags 6 positional
+    # args) without changing the underlying algorithm.
+    def compute_promoted_files(file_owner, file_uses, symbol_index, collided)
+      file_defs = symbol_index[:file_defs]
+      symbol_to_file = symbol_index[:symbol_to_file]
+      symbol_used_by_bundles = symbol_index[:symbol_used_by_bundles]
+      unpromotable = unpromotable_files(file_owner, file_defs, file_uses, symbol_to_file, collided)
+      promoted = Set.new
+      reasons = Hash.new { |h, k| h[k] = Set.new }
+
+      file_owner.each do |file_path, owner|
+        next if unpromotable.include?(file_path)
+
+        forcing = Set.new
+        file_defs[file_path].each do |sym|
+          # canonical-definer guard: only the file that canonically defines the
+          # symbol is eligible (resolves collisions to one file; excludes isolated
+          # dirs, which are never registered in symbol_to_file).
+          next unless symbol_to_file[sym] == file_path
+
+          (symbol_used_by_bundles[sym] - [owner]).each { |b| forcing << b }
+        end
+        next if forcing.empty?
+
+        promoted << file_path
+        reasons[relative_require_path(file_path)] = forcing
+      end
+
+      worklist = promoted.to_a
+      until worklist.empty?
+        current = worklist.pop
+        file_uses.fetch(current, Set.new).each do |sym|
+          dep_file = symbol_to_file[sym]
+          next unless dep_file
+          next if unpromotable.include?(dep_file)
+          next if promoted.include?(dep_file)
+
+          promoted << dep_file
+          reasons[relative_require_path(dep_file)] << "(transitive)"
+          worklist << dep_file
+        end
+      end
+
+      @promotion_reasons = reasons.transform_values(&:to_a)
+      promoted
+    end
+
+    # Indexes each controller dir's files and the PascalCase symbols they define.
+    # Returns [bundle_files, file_owner, file_defs, symbol_to_bundle, symbol_to_file,
+    # symbol_definers, bundle_own_symbols].
+    def index_controller_symbols(controller_dirs)
       bundle_files = {}
+      file_owner = {}
+      file_defs = Hash.new { |h, k| h[k] = Set.new }
       symbol_to_bundle = {}
+      symbol_to_file = {}
+      symbol_definers = Hash.new { |h, k| h[k] = Set.new }
       bundle_own_symbols = Hash.new { |h, k| h[k] = Set.new }
-      external_symbol_to_require = {}
-      dependencies = Hash.new { |h, k| h[k] = Set.new }
-      external_requires = Hash.new { |h, k| h[k] = Set.new }
 
       controller_dirs.each do |ctrl|
-        # Index controller-defined symbols for cross-app detection
         bundle_name = ctrl[:bundle_name]
         files = js_files_in(ctrl[:path])
         bundle_files[bundle_name] = files
-
         isolated = @config.isolated_app_dirs.include?(ctrl[:name])
 
         files.each do |file_path|
+          file_owner[file_path] = bundle_name
           extract_defined_symbols(file_path).each do |sym|
             next unless sym.match?(/\A[A-Z][A-Za-z0-9_]*\z/)
 
-            # Isolated dirs never register into the shared symbol index, so
-            # no other bundle can ever be inferred to depend on them —
-            # regardless of what their own symbol names happen to collide
-            # with (regex-based usage detection can't tell a real component
-            # reference from an unrelated word appearing as plain JSX text).
-            symbol_to_bundle[sym] ||= bundle_name unless isolated
+            file_defs[file_path] << sym
+            # Isolated dirs never register into the shared symbol index, so no
+            # other bundle can ever be inferred to depend on them.
+            unless isolated
+              symbol_to_bundle[sym] ||= bundle_name
+              symbol_to_file[sym]   ||= file_path
+              symbol_definers[sym] << file_path
+            end
             bundle_own_symbols[bundle_name] << sym
           end
         end
       end
 
-      # Index symbols from external_roots dirs
+      [bundle_files, file_owner, file_defs, symbol_to_bundle, symbol_to_file,
+       symbol_definers, bundle_own_symbols]
+    end
+
+    # Records, per controller file and per bundle, which symbols are used —
+    # plus a pseudo-bundle entry (config.shared_bundle) for any controller
+    # symbol referenced from a shared-dir file (shared code loads on every
+    # page, so that symbol's owning file must be treated as externally used).
+    def record_symbol_usages(bundle_files, shared_dirs, file_uses, symbol_used_by_bundles)
+      bundle_files.each do |bundle_name, files|
+        files.each do |file_path|
+          extract_used_component_symbols(file_path).each do |sym|
+            file_uses[file_path] << sym
+            symbol_used_by_bundles[sym] << bundle_name
+          end
+        end
+      end
+
+      shared_dirs.each do |dir|
+        js_files_in(dir[:path]).each do |file_path|
+          extract_used_component_symbols(file_path).each do |sym|
+            symbol_used_by_bundles[sym] << @config.shared_bundle
+          end
+        end
+      end
+    end
+
+    # Indexes symbols from external_roots dirs, then lets explicit
+    # external_providers win over scanned roots on symbol conflicts.
+    def index_external_symbols(symbol_to_bundle)
+      external_symbol_to_require = {}
+
       @config.external_roots.each do |root_path|
         abs_root = abs_external_root(root_path)
         external_js_files_in(abs_root).each do |file_path|
           req_path = relative_require_path(file_path)
-
           warn_on_external_controller_references(file_path, symbol_to_bundle)
-
           extract_defined_symbols(file_path).each do |sym|
             external_symbol_to_require[sym] ||= req_path
           end
         end
       end
 
-      # Explicit external_providers win over scanned roots on symbol conflicts
       @config.external_providers.each do |sym, req_path|
         external_symbol_to_require[sym] = req_path
       end
 
-      # Compute per-bundle cross-app and external dependencies
+      external_symbol_to_require
+    end
+
+    # Cross-app dependency graph + external requires (dependencies kept for
+    # reporting). Returns [dependencies, external_requires].
+    def build_dependency_graph(bundle_files, bundle_own_symbols, file_uses, symbol_to_bundle,
+                               external_symbol_to_require)
+      dependencies = Hash.new { |h, k| h[k] = Set.new }
+      external_requires = Hash.new { |h, k| h[k] = Set.new }
+
       bundle_files.each do |bundle_name, files|
         own_symbols = bundle_own_symbols[bundle_name]
-
         files.each do |file_path|
-          extract_used_component_symbols(file_path).each do |sym|
-            # A symbol the bundle defines itself (in any of its own files) is
-            # always satisfied locally — never attribute it to another bundle
-            # or an external provider just because that symbol name happens
-            # to collide with something defined elsewhere.
+          file_uses[file_path].each do |sym|
             next if own_symbols.include?(sym)
 
             dep_bundle = symbol_to_bundle[sym]
@@ -207,24 +459,82 @@ module ReactManifest
         end
       end
 
-      always_include_requires = build_always_include_requires(bundle_files, dependencies)
+      [dependencies, external_requires]
+    end
 
-      {
-        bundle_files: bundle_files,
-        dependencies: dependencies,
-        always_include_requires: always_include_requires,
-        external_requires: external_requires
-      }
+    # Under auto_shared, single-definer cross-used files live in ux_shared, so a
+    # controller only needs the canonical files for the symbols it uses that are NOT
+    # promoted (collided names kept bundle-local, plus their transitive needs).
+    # File-level + transitive so we never over-inline a whole dependency bundle
+    # (which could double-declare against an always_include bundle's own copy).
+    def promoted_aware_dependency_requires(bundle_name, controller_context)
+      # Symbols already on every page via an always_include tag. Skipped so a
+      # controller never inlines a (possibly colliding) second definer. Disabled
+      # when building an always_include bundle's own manifest (it needs its deps).
+      always_provided = always_provided_for(bundle_name, controller_context)
+      promoted_aware_dependency_files(bundle_name, controller_context, always_provided)
+        .map { |f| relative_require_path(f) }
+        .uniq
+        .sort
+    end
+
+    # Absolute paths of the non-promoted files a bundle must inline: for each
+    # symbol it uses (transitively) that is neither its own, promoted to shared,
+    # nor +always_provided+ on the page, the canonical (first-writer) definer file.
+    def promoted_aware_dependency_files(bundle_name, controller_context, always_provided)
+      own       = controller_context[:bundle_own_symbols].fetch(bundle_name, Set.new)
+      promoted  = controller_context[:promoted_files]
+      file_uses = controller_context[:file_uses]
+      sym2file  = controller_context[:symbol_to_file]
+      own_files = controller_context[:bundle_files].fetch(bundle_name, [])
+
+      needed = Set.new
+      seen   = Set.new
+      worklist = own_files.flat_map { |f| file_uses.fetch(f, Set.new).to_a }
+
+      until worklist.empty?
+        sym = worklist.pop
+        next if seen.include?(sym)
+
+        seen << sym
+        next if own.include?(sym)
+        next if always_provided.include?(sym)
+
+        dep_file = sym2file[sym]
+        next unless dep_file
+        next if promoted.include?(dep_file) # already served by ux_shared
+        next if own_files.include?(dep_file) # own file, added via own_requires
+        next if needed.include?(dep_file)
+
+        needed << dep_file
+        file_uses.fetch(dep_file, Set.new).each { |s| worklist << s unless seen.include?(s) }
+      end
+
+      needed
     end
 
     def controller_dependency_requires(bundle_name, controller_context)
       deps = transitive_dependencies(bundle_name, controller_context[:dependencies])
+      # Drop always_include bundles (and their transitive deps): they load on
+      # every page via their own <script> tag, so inlining them here would
+      # double-declare. Kept when the current bundle IS an always_include bundle.
+      always = controller_context[:always_loaded_bundles]
+      deps -= always.to_a unless always.include?(bundle_name)
       deps.flat_map { |dep_bundle| controller_context[:bundle_files].fetch(dep_bundle, []) }
           .map { |abs_path| relative_require_path(abs_path) }
           .uniq
           .sort
     end
 
+    # Symbols delivered on every page by an always_include tag, for +bundle_name+.
+    # Empty when building an always_include bundle's own manifest so it still
+    # inlines the dependencies it needs.
+    def always_provided_for(bundle_name, controller_context)
+      return Set.new if controller_context[:always_loaded_bundles].include?(bundle_name)
+
+      controller_context[:always_provided_symbols]
+    end
+
     def transitive_dependencies(bundle_name, dependency_map)
       ordered = []
       visiting = Set.new
@@ -245,30 +555,16 @@ module ReactManifest
       ordered
     end
 
-    def build_always_include_requires(bundle_files, dependencies)
+    # The set of bundles guaranteed loaded on every page by always_include: each
+    # configured always_include bundle plus its transitive dependencies. These
+    # arrive via their own <script> tag (resolve_bundles / react_component), so
+    # controller manifests must never inline their files or symbols.
+    def compute_always_loaded_bundles(dependencies)
       bundles = @config.always_include.map(&:to_s).reject(&:empty?).uniq
-      return Hash.new { |h, k| h[k] = [] } if bundles.empty?
-
-      requires_by_bundle = Hash.new { |h, k| h[k] = [] }
-
-      bundle_files.each_key do |bundle_name|
-        requires = Set.new
-
-        bundles.each do |always_bundle|
-          next if always_bundle == bundle_name
-
-          transitive = [always_bundle] + transitive_dependencies(always_bundle, dependencies)
-          transitive.each do |dep_bundle|
-            bundle_files.fetch(dep_bundle, []).each do |abs_path|
-              requires << relative_require_path(abs_path)
-            end
-          end
-        end
-
-        requires_by_bundle[bundle_name] = requires.to_a.sort
+      bundles.each_with_object(Set.new) do |always_bundle, acc|
+        acc << always_bundle
+        transitive_dependencies(always_bundle, dependencies).each { |dep| acc << dep }
       end
-
-      requires_by_bundle
     end
 
     # --------------------------------------------------------------- write

data/lib/react_manifest/gitignore_patcher.rb

@@ -0,0 +1,75 @@
+require "fileutils"
+
+module ReactManifest
+  # Ensures the generated manifest dir is gitignored and that a committed .keep
+  # keeps the directory present on a fresh clone. Idempotent and best-effort:
+  # a filesystem error logs a warning and never raises.
+  class GitignorePatcher
+    include ReactManifest::Logging
+
+    Result = Struct.new(:appended, :keep_created, keyword_init: true)
+
+    def initialize(config = ReactManifest.configuration)
+      @config = config
+    end
+
+    def patch!
+      Result.new(appended: ensure_gitignore_entry, keep_created: ensure_keep)
+    end
+
+    # patch! plus a one-time hint to untrack previously-committed manifests when the
+    # .gitignore entry was just added (the gem never runs git itself). Returns true
+    # iff the .gitignore entry was appended.
+    def reconcile!
+      result = patch!
+      if result.appended
+        base = File.dirname(pattern)
+        log_info "If #{base}/*.js were previously committed, untrack them once: " \
+                 "git rm --cached #{base}/*.js"
+      end
+      result.appended
+    end
+
+    # Path (relative to Rails.root) that should be ignored, e.g.
+    # "app/assets/javascripts/ux_manifests/*.js".
+    def pattern
+      subdir = @config.normalized_manifest_subdir
+      base   = subdir.empty? ? @config.output_dir : File.join(@config.output_dir, subdir)
+      File.join(base, "*.js")
+    end
+
+    private
+
+    def gitignore_path
+      Rails.root.join(".gitignore").to_s
+    end
+
+    def ensure_gitignore_entry
+      path    = gitignore_path
+      line    = pattern
+      content = File.exist?(path) ? File.read(path, encoding: "utf-8") : ""
+      return false if content.split("\n").map(&:strip).include?(line)
+
+      prefix = content.empty? || content.end_with?("\n") ? "" : "\n"
+      File.open(path, "a") { |f| f.write("#{prefix}#{line}\n") }
+      log_info "Added #{line} to .gitignore"
+      true
+    rescue Errno::EACCES, Errno::ENOENT => e
+      log_warn "Could not update .gitignore: #{e.message}"
+      false
+    end
+
+    def ensure_keep
+      dir  = @config.abs_manifest_dir
+      keep = File.join(dir, ".keep")
+      return false if File.exist?(keep)
+
+      FileUtils.mkdir_p(dir)
+      FileUtils.touch(keep)
+      true
+    rescue Errno::EACCES => e
+      log_warn "Could not create #{dir}/.keep: #{e.message}"
+      false
+    end
+  end
+end

data/lib/react_manifest/railtie.rb

@@ -26,6 +26,12 @@ module ReactManifest
         Rails.logger&.warn(error)
         $stdout.puts(error) if config.stdout_logging?
       end
+
+      begin
+        ReactManifest.reconcile_gitignore!(config)
+      rescue StandardError => e
+        Rails.logger&.warn("[ReactManifest] gitignore reconcile failed: #{e.message}")
+      end
     end
 
     # Expose config as Rails.application.config.react_manifest

data/lib/react_manifest/version.rb

@@ -1,3 +1,3 @@
 module ReactManifest
-  VERSION = "0.2.34".freeze
+  VERSION = "0.3.0".freeze
 end

data/lib/react_manifest.rb

@@ -14,6 +14,7 @@ require "react_manifest/application_analyzer"
 require "react_manifest/application_migrator"
 require "react_manifest/layout_patcher"
 require "react_manifest/sprockets_manifest_patcher"
+require "react_manifest/gitignore_patcher"
 require "react_manifest/watcher"
 require "react_manifest/reporter"
 require "react_manifest/view_helpers"
@@ -55,10 +56,7 @@ module ReactManifest
       bundles << shared if shared
 
       # 2. always_include bundles (e.g. ux_main)
-      config.always_include.each do |b|
-        resolved = resolve_bundle_reference(config, b)
-        bundles << resolved if resolved && !bundles.include?(resolved)
-      end
+      append_always_include(config, bundles)
 
       # 3. Controller-specific bundle
       # Try fully-namespaced first: admin/users → ux_admin_users
@@ -74,6 +72,18 @@ module ReactManifest
       bundles
     end
 
+    # Ensure the manifest dir is gitignored (and .keep present). Honors
+    # config.manage_gitignore. Returns true if it appended the .gitignore entry.
+    # Best-effort: a filesystem error is logged and swallowed (never breaks boot).
+    def reconcile_gitignore!(config = configuration)
+      return false unless config.manage_gitignore?
+
+      GitignorePatcher.new(config).reconcile!
+    rescue StandardError => e
+      Rails.logger&.warn("[ReactManifest] gitignore reconcile skipped: #{e.message}")
+      false
+    end
+
     # Resolve a controller bundle from a React component symbol.
     #
     # This is primarily used to support react-rails `react_component` calls,
@@ -102,6 +112,12 @@ module ReactManifest
       shared = resolve_bundle_reference(config, config.shared_bundle)
       bundles << shared if shared
 
+      # always_include bundles are delivered on every page. react_component does
+      # NOT go through resolve_bundles, so it must emit them here too — this is
+      # what makes always_include symbols available without inlining them into
+      # controller manifests (which would double-declare, see Generator).
+      append_always_include(config, bundles)
+
       root = resolve_bundle_reference(config, root_bundle)
       bundles << root if root && !bundles.include?(root)
 
@@ -142,6 +158,15 @@ module ReactManifest
 
     private
 
+    # Append each configured always_include bundle (deduped) to +bundles+.
+    def append_always_include(config, bundles)
+      config.always_include.each do |b|
+        resolved = resolve_bundle_reference(config, b)
+        bundles << resolved if resolved && !bundles.include?(resolved)
+      end
+      bundles
+    end
+
     def component_bundle_map(config)
       component_maps(config)[:symbol_to_bundle]
     end

data/tasks/react_manifest.rake

@@ -80,6 +80,22 @@ namespace :react_manifest do
       puts "   ✓ #{written} written, #{unchanged} unchanged"
     end
 
+    # 6. Ensure generated manifests are gitignored
+    puts "\n6) Gitignoring generated manifests..."
+    if config.manage_gitignore?
+      patcher = ReactManifest::GitignorePatcher.new(config)
+      result  = patcher.patch!
+      if result.appended
+        puts "   ✓ added #{patcher.pattern} to .gitignore"
+        puts "   → one-time cleanup for previously-committed manifests:"
+        puts "     git rm --cached #{File.dirname(patcher.pattern)}/*.js"
+      else
+        puts "   ✓ #{patcher.pattern} already ignored"
+      end
+    else
+      puts "   (skipped — config.manage_gitignore is false)"
+    end
+
     # Done
     puts "\n=== Setup #{'(dry-run) ' if config.dry_run?}complete ==="
     puts "Start your Rails server — react_bundle_tag will serve the right JS per controller." unless config.dry_run?
@@ -130,6 +146,14 @@ namespace :react_manifest do
     scan_result    = scanner.scan(classification)
     dep_map        = ReactManifest::DependencyMap.new(scan_result)
     dep_map.print_report
+
+    reasons = ReactManifest::Generator.new(config).promotion_reasons
+    unless reasons.empty?
+      puts "\nPromotions (app/ components emitted into #{config.shared_bundle}):"
+      reasons.sort.each do |req, bundles|
+        puts "  #{req}  <- used by: #{bundles.sort.join(', ')}"
+      end
+    end
   end
 
   desc "Analyze application*.js files — show what migrate_application would change"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-manifest-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.34
+  version: 0.3.0
 platform: ruby
 authors:
 - Oliver Noonan
@@ -155,6 +155,7 @@ files:
 - lib/react_manifest/configuration.rb
 - lib/react_manifest/dependency_map.rb
 - lib/react_manifest/generator.rb
+- lib/react_manifest/gitignore_patcher.rb
 - lib/react_manifest/layout_patcher.rb
 - lib/react_manifest/logging.rb
 - lib/react_manifest/path_utils.rb