react-manifest-rails 0.2.34 → 0.3.1

data/lib/react_manifest/generator.rb

@@ -42,20 +42,21 @@ 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
     # in a second pass so that a failure midway does not leave some bundles
     # written and others stale/missing.
     def run!
-      classification = @classifier.classify
-      controller_context = build_controller_context(classification.controller_dirs)
-
-      # Phase 1: build all content in memory — no I/O.
-      shared_manifest = build_shared(classification.shared_dirs)
-      manifests = [shared_manifest] + classification.controller_dirs.map do |ctrl|
-        build_controller(ctrl, controller_context)
-      end
+      classification, manifests = build_manifests
 
       migrate_legacy_manifests!
 
@@ -68,10 +69,20 @@ module ReactManifest
       expected_filenames = manifests.map { |m| m[:filename] }
       results.concat(remove_orphaned_manifests(expected_filenames))
 
+      ComponentIndex.write!(@config, classification.controller_dirs) unless @config.dry_run?
+
       print_summary(results) if @config.verbose?
       results
     end
 
+    # Analyse without writing anything. Returns the "declared twice" warnings
+    # (cross-bundle top-level const/let/class collisions and always_include
+    # double-declares); empty when clean. Backs `rake react_manifest:check`.
+    def check
+      build_manifests
+      @clashes
+    end
+
     # Remove all AUTO-GENERATED ux_*.js manifests. Silently skips files that
     # disappear between the directory scan and the read (TOCTOU-safe).
     # Returns { removed: N, skipped: N }.
@@ -91,6 +102,8 @@ module ReactManifest
         end
       end
 
+      FileUtils.rm_f(ComponentIndex.path(@config))
+
       { removed: removed, skipped: skipped }
     end
 
@@ -98,10 +111,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 +131,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 +156,390 @@ 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 collision cases dependency arithmetic cannot resolve. A collided
+    # symbol (2+ app-dir definers) has no collision-free page-global home, so a file
+    # that defines or transitively depends on one can never be promoted to ux_shared;
+    # it is inlined into whichever always_include tag(s) reach it and double-declares:
+    #
+    #   * multi-tag (every page): the same file is carried by 2+ always_include tags.
+    #     Both tags load on every page, so it double-declares everywhere — whether it
+    #     DEFINES the collided symbol or merely depends on one (a tainted file).
+    #   * owner-page: the file is carried by a single always_include tag but also lives
+    #     in its own controller's manifest, so it double-declares on that owner's page.
+    #
+    # We cannot auto-fix either (there is no safe shared 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
+      return if bundles.empty?
+
+      tags_by_file = Hash.new { |h, k| h[k] = [] }
+      bundles.each { |b| always_bundle_tag_files(b, context).each { |f| tags_by_file[f] << b } }
+
+      tags_by_file.each do |file, tags|
+        owner = file_owner[file]
+        next if tags.size < 2 && (owner.nil? || tags.include?(owner))
+
+        syms = collided_symbols_reachable(file, file_defs, context, collided).to_a.sort
+        next if syms.empty?
+
+        what = "'#{relative_require_path(file)}' (#{collision_phrase(file, file_defs, collided, syms)})"
+        fix = "Rename the symbol or move it to a uniquely-named shared component."
+        if tags.size > 1
+          report_clash "always_include bundles #{tags.sort.join(', ')} all pull in #{what}. Each of those " \
+                       "bundles loads on every page via its own <script> tag, so that file loads more " \
+                       "than once on every page — a duplicate declaration. #{fix}"
+        else
+          report_clash "always_include bundle '#{tags.first}' pulls in #{what} owned by '#{owner}'. On " \
+                       "#{owner}'s own page that file loads twice — once via the #{tags.first} tag and " \
+                       "once via #{owner} — causing a duplicate declaration. #{fix}"
+        end
+      end
+    end
+
+    # Classic scripts share ONE global lexical scope, and under Turbolinks one window
+    # loads many pages' bundles. Two DIFFERENT files declaring the same top-level
+    # const/let/class in different bundles (a controller bundle vs another, or vs
+    # ux_shared) throw "Identifier already declared" and the later bundle is rejected.
+    # Works from the built manifests so a promoted file counts once (in ux_shared) and
+    # one file inlined into two bundles (the existing double-declare case) is not
+    # reported here: it takes two distinct declaring files across 2+ bundles.
+    def warn_on_cross_bundle_lexical_collisions(manifests, classification)
+      file_for = {}
+      (classification.shared_dirs + classification.controller_dirs).each do |d|
+        js_files_in(d[:path]).each { |f| file_for[relative_require_path(f)] = f }
+      end
+
+      bundles_by_name_file = Hash.new { |h, name| h[name] = Hash.new { |h2, f| h2[f] = Set.new } }
+      bindings = Hash.new { |h, f| h[f] = ComponentIndex.extract(f, :extract_lexical_bindings) }
+      manifests.each do |m|
+        bundle = File.basename(m[:filename], ".js")
+        m[:content].scan(%r{^//= require (\S+)$}) do |(req)|
+          file = file_for[req] or next
+          bindings[file].each { |name| bundles_by_name_file[name][file] << bundle }
+        end
+      end
+
+      bundles_by_name_file.sort.each do |name, files|
+        next if files.size < 2 || files.values.reduce(:|).size < 2
+
+        where = files.map { |f, bs| "#{relative_require_path(f)} (#{bs.to_a.sort.join(', ')})" }.join("; ")
+        report_clash "Top-level binding '#{name}' is declared by different files in different bundles: #{where}. " \
+                     "Under Turbolinks these share one global scope, so loading both bundles throws " \
+                     "\"Identifier '#{name}' has already been declared\" and rejects the second. " \
+                     "Move it inside the component body, rename it, or move the file into a shared directory."
+      end
+    end
+
+    # "defines collided symbol X" for a direct definer, "depends on ..." for a tainted file.
+    def collision_phrase(file, file_defs, collided, syms)
+      relation = (file_defs.fetch(file, Set.new) & collided).empty? ? "depends on" : "defines"
+      "#{relation} collided symbol#{'s' if syms.size > 1} #{syms.join(', ')}"
+    end
+
+    # Every file an always_include bundle's tag delivers: its own non-promoted files
+    # plus the foreign dependency files it inlines. Used to detect a file carried by
+    # more than one tag (double-loaded on every page).
+    def always_bundle_tag_files(always_bundle, context)
+      own = context[:bundle_files].fetch(always_bundle, [])
+                                  .reject { |f| context[:promoted_files].include?(f) }
+      own + always_include_foreign_files(always_bundle, context).to_a
+    end
+
+    # Collided symbols a file defines or transitively depends on: follows file_uses →
+    # canonical definer file, collecting every collided symbol reached along the way.
+    def collided_symbols_reachable(file, file_defs, context, collided)
+      file_uses = context[:file_uses]
+      sym2file  = context[:symbol_to_file]
+      result = Set.new
+      seen   = Set.new
+      stack  = [file]
+
+      until stack.empty?
+        current = stack.pop
+        next if seen.include?(current)
+
+        seen << current
+        result.merge(file_defs.fetch(current, Set.new) & collided)
+        file_uses.fetch(current, Set.new).each do |sym|
+          result << sym if collided.include?(sym)
+          dep = sym2file[sym]
+          stack << dep if dep && !seen.include?(dep)
+        end
+      end
+
+      result
+    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|
-          extract_defined_symbols(file_path).each do |sym|
+          file_owner[file_path] = bundle_name
+          ComponentIndex.extract(file_path, :extract_definitions).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|
+          ComponentIndex.extract(file_path, :extract_usages).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|
+          ComponentIndex.extract(file_path, :extract_usages).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|
+          ComponentIndex.extract(file_path, :extract_definitions).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 +551,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 +647,36 @@ 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
+      bundles.each_with_object(Set.new) do |always_bundle, acc|
+        acc << always_bundle
+        transitive_dependencies(always_bundle, dependencies).each { |dep| acc << dep }
+      end
+    end
 
-          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
+    # Phase 1: build all content in memory — no I/O besides reading sources.
+    def build_manifests
+      @clashes = []
+      classification = @classifier.classify
+      controller_context = build_controller_context(classification.controller_dirs, classification.shared_dirs)
 
-        requires_by_bundle[bundle_name] = requires.to_a.sort
+      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
 
-      requires_by_bundle
+      warn_on_cross_bundle_lexical_collisions(manifests, classification)
+      [classification, manifests]
+    end
+
+    def report_clash(message)
+      @clashes << message
+      log_warn message
     end
 
     # --------------------------------------------------------------- write
@@ -393,20 +801,6 @@ module ReactManifest
       strip_asset_extension(rel)
     end
 
-    def extract_defined_symbols(file_path)
-      content = File.read(file_path, encoding: "utf-8")
-      SymbolExtractor.extract_definitions(content, file_path: file_path)
-    rescue Errno::ENOENT, Errno::EACCES, Encoding::InvalidByteSequenceError
-      []
-    end
-
-    def extract_used_component_symbols(file_path)
-      content = File.read(file_path, encoding: "utf-8")
-      SymbolExtractor.extract_usages(content, file_path: file_path)
-    rescue Errno::ENOENT, Errno::EACCES, Encoding::InvalidByteSequenceError
-      []
-    end
-
     def external_js_files_in(dir)
       return [] unless Dir.exist?(dir)
 
@@ -427,7 +821,7 @@ module ReactManifest
     end
 
     def warn_on_external_controller_references(file_path, symbol_to_bundle)
-      extract_used_component_symbols(file_path).each do |sym|
+      ComponentIndex.extract(file_path, :extract_usages).each do |sym|
         dep_bundle = symbol_to_bundle[sym]
         next unless dep_bundle