react-manifest-rails 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42ca130740decc2c19123ab8e2d0b368925f0bd988736d84a9087d4016e1836c
-  data.tar.gz: e9e23a7c0eb8dea12f4eb8498f08bff0ea11fe56f168833ae3ef13e090b4d59a
+  metadata.gz: d5ea479337143141722feeaa26cbf9e8d46e2158c399f5d29f4cb6bc5dbbdcd7
+  data.tar.gz: 0d4983f0b8ec3c35d7165fbfe801fc3f73286868e88bca1da83e76f6dcf963ce
 SHA512:
-  metadata.gz: d73c047a2257f229e26682658c2644c0645fd362ba30f2f2ef34fceb15ecf83cf282b2c7899472e3eb25351b30512b5a3e8dbe456e1057502453876f2ce1868d
-  data.tar.gz: 78ebfd5b3390fa6204d6a59a46d94f1aef87c87359b499049f745da68d493f2dab3dd4fefe1f46667ca1be40f66c02e17fa1b977f3fc5b67370a9ba37a9b0566
+  metadata.gz: dfeba95401019cb1233677138d89b99d9c286d55c89edc74fd1e9f10e4ade37f0038cfede9d12045a43d0143355c622c9c746178d0a8da75c3c6cf97e62b9a79
+  data.tar.gz: 29159646362cbdb7be57a57fdc77fd61010e607c7dfe2214f65e301b352b44914e1749304bb0f6e457b2cab97f0627f34ea5dfbbef1597ed3a93951069389baa

data/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-10-13
+
+### Added
+- `react_component` adds `data-react-persist="true"` to the root element when it runs after
+  `react_bundle_tag` in the same request. That is a component in the layout body (navbar,
+  footer, sidebar), since Rails renders the template first. A Turbolinks wrapper can keep it
+  mounted across visits and pass it new props. Template components are never marked.
+
+## [0.3.1] - 2026-10-13
+
+### Added
+- `react_bundle_tag` emits `data-turbolinks-track="reload"` on the shared bundle's tag only
+  (`config.shared_bundle`). Turbolinks 5 then full-reloads once after a deploy changes
+  `ux_shared`, so old shared code never runs with new controller code. Controller and
+  `always_include` bundles stay untracked to avoid a reload on every cross-controller visit.
+- `react_manifest:generate` warns when two different files declare the same top-level
+  `const`/`let`/`class` (destructured names included) in different bundles. Classic scripts
+  share one global scope, so under Turbolinks the second bundle throws "Identifier X has
+  already been declared" and is rejected.
+- `react_manifest:generate` (and the dev boot/watch generation) writes
+  `ux_manifests/component_index.json`, the component-symbol -> bundle maps. `react_component`
+  loads it instead of parsing `ux/app` with mini_racer on each process's first call (no V8
+  context, no per-worker RSS cost). It is used only when its content fingerprint matches;
+  a missing or stale sidecar falls back to the runtime parse. Gitignored alongside the
+  manifests; removed by `react_manifest:clean`.
+- `rake react_manifest:check`: analysis only, writes nothing, exits 1 with the warnings on
+  stderr when any "declared twice" clash is found (cross-bundle lexical collisions,
+  `always_include` double-declares). Meant for CI.
+
+### Fixed
+- `mini_racer` is now a declared runtime dependency (`>= 0.2`); `AstExtractor` already
+  required it unconditionally.
+- The built gem no longer ships `lib/react_manifest/vendor/build/node_modules`.
+- `react_bundle_tag` now hoists bundle `<script>` tags into the layout `<head>`. Rails renders
+  the template before the layout, so `react_component` wrote ux_shared, `always_include` and
+  controller bundle tags into the `<body>`; Turbolinks re-evaluates body scripts on every
+  visit, giving "Identifier X has already been declared". `react_component` now marks its
+  inline tags (`data-react-manifest`) and `react_bundle_tag` moves them to the head, once, in
+  shared → always_include → controller order. Layouts without `react_bundle_tag` are unchanged.
+- Collision warnings for `always_include` bundles now cover the every-page double.
+  Previously only a file that **directly** defined a collided symbol was warned about.
+  A file that is merely *tainted* (transitively depends on a collided symbol) and gets
+  pulled into **2+** `always_include` tags double-declares on every page but was not
+  warned. The warning now reports both a *multi-tag* double (a file carried by 2+
+  always_include tags — including tainted files, naming the file, symbol, and bundles)
+  and the *owner-page* double (single tag vs. the owning bundle), with wording accurate
+  to each case rather than always claiming the double happens "on the owner's page".
+
 ## [0.3.0] - 2026-07-15
 
 ### Fixed

data/README.md

@@ -143,13 +143,14 @@ end
 ### Key option notes
 
 - **`ignore`**: skips entire controller dirs under `ux/app/`. `ignore = ["admin"]` excludes `ux/app/admin/`.
-- **`isolated_app_dirs`**: a controller dir's own `ux_<name>.js` is generated as usual, but its files/symbols are never inferred as a dependency of any *other* controller. Without the optional AST engine below (i.e. no `mini_racer`), symbol usage detection is regex-based, so a generic component name can collide with an unrelated word appearing as plain JSX text elsewhere (e.g. a `Show` component vs. a "Show More" button label in a different controller) and get wrongly inlined everywhere. Use this as a manual, always-available fallback for self-contained dirs — e.g. a page-builder tool bundling its own vendored library — that should never leak into other pages, whether or not `mini_racer` is installed. `isolated_app_dirs = ["rvb"]` isolates `ux/app/rvb/`.
+- **`isolated_app_dirs`**: a controller dir's own `ux_<name>.js` is generated as usual, but its files/symbols are never inferred as a dependency of any *other* controller. When the AST engine below is unavailable (e.g. `mini_racer` failed to load), symbol usage detection is regex-based, so a generic component name can collide with an unrelated word appearing as plain JSX text elsewhere (e.g. a `Show` component vs. a "Show More" button label in a different controller) and get wrongly inlined everywhere. Use this as a manual, always-available fallback for self-contained dirs — e.g. a page-builder tool bundling its own vendored library — that should never leak into other pages, whether or not `mini_racer` is installed. `isolated_app_dirs = ["rvb"]` isolates `ux/app/rvb/`.
 - **`exclude_paths`**: excludes files whose path contains any listed segment. Not based on `application.js`.
 - **`dry_run`**: also honoured by `DRY_RUN=1` environment variable at runtime.
 - **`extensions`**: add `ts` and `tsx` to enable TypeScript source detection.
 - **`external_roots` / `external_providers`**: do not point these at files already inside shared `ux/` dirs (`components/`, `hooks/`, `lib/`, etc.). The generator now skips those overlaps to prevent duplicate declarations in browser runtime.
 - **`stdout_logging`**: `Rails.logger` always receives status lines regardless of this flag. Turn this on only if your `Rails.logger` does *not* already print to your terminal in development — if it does (common with `RAILS_LOG_TO_STDOUT`, Docker, or `bin/dev`/Foreman setups), enabling this prints every line twice.
-- **AST-based symbol extraction**: add `gem "mini_racer"` to your Gemfile to opt in. When present, definitions and usages are derived from a real JS/JSX AST (Acorn) instead of regex, which fixes false positives like a `Show` component colliding with unrelated text such as a "Show More" button label. Falls back to regex extraction per-file on any parse failure (always logged via `Rails.logger.warn` with file/line/column when available) — generation never breaks because of this. Without `mini_racer`, behavior is unchanged from today.
+- **Component index**: `react_manifest:generate` (and dev boot/watch) also writes `ux_manifests/component_index.json`, a gitignored build artifact. `react_component` reads it instead of parsing `ux/app` with V8 on the first call in each web process. It is used only when its fingerprint (gem version, config, file list and contents) matches; otherwise the runtime parses as before.
+- **AST-based symbol extraction**: `mini_racer` is a dependency of this gem. Definitions and usages are derived from a real JS/JSX AST (Acorn) instead of regex, which fixes false positives like a `Show` component colliding with unrelated text such as a "Show More" button label. Falls back to regex extraction per-file on any parse failure (always logged via `Rails.logger.warn` with file/line/column when available) — generation never breaks because of this.
 
 ## Commands
 
@@ -164,6 +165,10 @@ bundle exec rails react_manifest:generate
 DRY_RUN=1 bundle exec rails react_manifest:setup
 DRY_RUN=1 bundle exec rails react_manifest:generate
 
+# CI gate: writes nothing; exits 1 and prints each "declared twice" warning to stderr
+# (cross-bundle top-level const/let/class clashes, always_include double-declares)
+bundle exec rails react_manifest:check
+
 # Analyse which shared symbols are used per controller
 bundle exec rails react_manifest:analyze
 

data/lib/react_manifest/ast_extractor.rb

@@ -15,6 +15,9 @@ module ReactManifest
       function __reactManifestExtractDefinitions(content) {
         return JSON.stringify(__astExtractor.extractDefinitions(content));
       }
+      function __reactManifestExtractLexicalBindings(content) {
+        return JSON.stringify(__astExtractor.extractLexicalBindings(content));
+      }
       function __reactManifestExtractUsages(content) {
         return JSON.stringify(__astExtractor.extractUsages(content));
       }
@@ -31,6 +34,14 @@ module ReactManifest
         nil
       end
 
+      def extract_lexical_bindings(content, file_path: nil)
+        result = call_js("__reactManifestExtractLexicalBindings", content)
+        return result["bindings"] if result["success"]
+
+        report_error(file_path, result["error"])
+        nil
+      end
+
       def extract_usages(content, file_path: nil)
         result = call_js("__reactManifestExtractUsages", content)
         return result["usages"] if result["success"]

data/lib/react_manifest/component_index.rb

@@ -0,0 +1,136 @@
+require "digest"
+require "json"
+require "set"
+
+module ReactManifest
+  # The component-symbol -> bundle maps behind react_component bundle resolution.
+  #
+  # Parsing ux/app needs a V8 context (tens of MB per process), so the generator
+  # writes the maps to a JSON sidecar next to the generated manifests and the
+  # runtime loads that instead. The sidecar carries a fingerprint of everything the
+  # maps are derived from (gem version, config, controller dirs, file paths and
+  # contents); a missing, unreadable or mismatching sidecar falls back to parsing.
+  module ComponentIndex
+    FILENAME = "component_index.json".freeze
+
+    module_function
+
+    def path(config)
+      File.join(config.abs_manifest_dir, FILENAME)
+    end
+
+    # Sidecar maps when fresh, else freshly parsed ones.
+    def maps(config)
+      controller_dirs = TreeClassifier.new(config).classify.controller_dirs
+      load_fresh(config, controller_dirs) || build(config, controller_dirs)
+    end
+
+    # Write the sidecar (skipped when unchanged). Returns the path.
+    def write!(config, controller_dirs)
+      dest = path(config)
+      json = JSON.generate(serialize(config, controller_dirs, build(config, controller_dirs)))
+      return dest if File.exist?(dest) && File.read(dest, encoding: "utf-8") == json
+
+      FileUtils.mkdir_p(File.dirname(dest))
+      File.write(dest, json, encoding: "utf-8")
+      dest
+    end
+
+    def build(config, controller_dirs)
+      symbol_to_bundle = {}
+      bundle_own_symbols = Hash.new { |h, k| h[k] = Set.new }
+      bundle_files = Hash.new { |h, k| h[k] = [] }
+      bundle_dependencies = Hash.new { |h, k| h[k] = Set.new }
+
+      controller_dirs.each do |ctrl|
+        bundle_name = ctrl[:bundle_name]
+        files = js_files_in_controller(ctrl[:path], config)
+        bundle_files[bundle_name].concat(files)
+        isolated = config.isolated_app_dirs.include?(ctrl[:name])
+
+        files.each do |file_path|
+          extract(file_path, :extract_definitions).each do |symbol|
+            next unless symbol.match?(/\A[A-Z][A-Za-z0-9_]*\z/)
+
+            # Keep first writer to ensure deterministic behavior if a symbol is duplicated.
+            # Isolated dirs never register into the shared symbol index (see
+            # Generator#build_controller_context for the full rationale).
+            symbol_to_bundle[symbol] ||= bundle_name unless isolated
+            bundle_own_symbols[bundle_name] << symbol
+          end
+        end
+      end
+
+      bundle_files.each do |bundle_name, files|
+        own_symbols = bundle_own_symbols[bundle_name]
+
+        files.each do |file_path|
+          extract(file_path, :extract_usages).each do |symbol|
+            # A symbol the bundle defines itself is always satisfied locally —
+            # never attribute it to another bundle just because that symbol
+            # name happens to collide with something defined elsewhere.
+            next if own_symbols.include?(symbol)
+
+            dep_bundle = symbol_to_bundle[symbol]
+            next unless dep_bundle && dep_bundle != bundle_name
+
+            bundle_dependencies[bundle_name] << dep_bundle
+          end
+        end
+      end
+
+      { symbol_to_bundle: symbol_to_bundle, bundle_dependencies: bundle_dependencies }
+    end
+
+    def load_fresh(config, controller_dirs)
+      data = JSON.parse(File.read(path(config), encoding: "utf-8"))
+      return unless data["fingerprint"] == fingerprint(config, controller_dirs)
+
+      bundle_dependencies = Hash.new { |h, k| h[k] = Set.new }
+      data["bundle_dependencies"].each { |bundle, deps| bundle_dependencies[bundle] = deps.to_set }
+      { symbol_to_bundle: data["symbol_to_bundle"], bundle_dependencies: bundle_dependencies }
+    rescue StandardError
+      nil
+    end
+
+    def serialize(config, controller_dirs, maps)
+      {
+        "fingerprint" => fingerprint(config, controller_dirs),
+        "symbol_to_bundle" => maps[:symbol_to_bundle],
+        "bundle_dependencies" => maps[:bundle_dependencies].transform_values { |deps| deps.to_a.sort }
+      }
+    end
+
+    # Digest of every input the maps depend on. File paths are relative to ux_root so
+    # a relocated release dir stays valid; contents (not mtimes) so a checkout that
+    # rewrites timestamps cannot make a stale sidecar look fresh or a fresh one stale.
+    def fingerprint(config, controller_dirs)
+      digest = Digest::SHA256.new
+      digest << JSON.generate([VERSION, config.extensions, config.isolated_app_dirs])
+      controller_dirs.each do |ctrl|
+        digest << "\0" << ctrl[:bundle_name]
+        js_files_in_controller(ctrl[:path], config).each do |file|
+          digest << "\0" << file.delete_prefix(config.abs_ux_root) << "\0" << File.binread(file)
+        rescue SystemCallError
+          digest << "\0unreadable"
+        end
+      end
+      digest.hexdigest
+    end
+
+    def js_files_in_controller(dir, config)
+      return [] unless Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "**", config.extensions_glob))
+         .reject { |f| File.directory?(f) }
+         .sort
+    end
+
+    def extract(file_path, method)
+      content = File.read(file_path, encoding: "utf-8")
+      SymbolExtractor.public_send(method, content, file_path: file_path)
+    rescue Errno::ENOENT, Errno::EACCES, Encoding::InvalidByteSequenceError
+      []
+    end
+  end
+end

data/lib/react_manifest/generator.rb

@@ -56,14 +56,7 @@ module ReactManifest
     # 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, classification.shared_dirs)
-
-      # Phase 1: build all content in memory — no I/O.
-      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
+      classification, manifests = build_manifests
 
       migrate_legacy_manifests!
 
@@ -76,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 }.
@@ -99,6 +102,8 @@ module ReactManifest
         end
       end
 
+      FileUtils.rm_f(ComponentIndex.path(@config))
+
       { removed: removed, skipped: skipped }
     end
 
@@ -207,34 +212,121 @@ module ReactManifest
       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.
+    # 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
-      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."
+      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
@@ -371,7 +463,7 @@ module ReactManifest
 
         files.each do |file_path|
           file_owner[file_path] = bundle_name
-          extract_defined_symbols(file_path).each do |sym|
+          ComponentIndex.extract(file_path, :extract_definitions).each do |sym|
             next unless sym.match?(/\A[A-Z][A-Za-z0-9_]*\z/)
 
             file_defs[file_path] << sym
@@ -398,7 +490,7 @@ module ReactManifest
     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|
+          ComponentIndex.extract(file_path, :extract_usages).each do |sym|
             file_uses[file_path] << sym
             symbol_used_by_bundles[sym] << bundle_name
           end
@@ -407,7 +499,7 @@ module ReactManifest
 
       shared_dirs.each do |dir|
         js_files_in(dir[:path]).each do |file_path|
-          extract_used_component_symbols(file_path).each do |sym|
+          ComponentIndex.extract(file_path, :extract_usages).each do |sym|
             symbol_used_by_bundles[sym] << @config.shared_bundle
           end
         end
@@ -424,7 +516,7 @@ module ReactManifest
         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
@@ -567,6 +659,26 @@ module ReactManifest
       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)
+
+      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
+
+      warn_on_cross_bundle_lexical_collisions(manifests, classification)
+      [classification, manifests]
+    end
+
+    def report_clash(message)
+      @clashes << message
+      log_warn message
+    end
+
     # --------------------------------------------------------------- write
 
     def write_manifest(filename, content)
@@ -689,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)
 
@@ -723,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
 

data/lib/react_manifest/gitignore_patcher.rb

@@ -30,6 +30,11 @@ module ReactManifest
       result.appended
     end
 
+    # The component-index sidecar written next to the manifests (see ComponentIndex).
+    def json_pattern
+      File.join(File.dirname(pattern), "*.json")
+    end
+
     # Path (relative to Rails.root) that should be ignored, e.g.
     # "app/assets/javascripts/ux_manifests/*.js".
     def pattern
@@ -46,13 +51,14 @@ module ReactManifest
 
     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)
+      lines   = content.split("\n").map(&:strip)
+      missing = [pattern, json_pattern] - lines
+      return false if missing.empty?
 
       prefix = content.empty? || content.end_with?("\n") ? "" : "\n"
-      File.open(path, "a") { |f| f.write("#{prefix}#{line}\n") }
-      log_info "Added #{line} to .gitignore"
+      File.open(path, "a") { |f| f.write("#{prefix}#{missing.join("\n")}\n") }
+      log_info "Added #{missing.join(', ')} to .gitignore"
       true
     rescue Errno::EACCES, Errno::ENOENT => e
       log_warn "Could not update .gitignore: #{e.message}"

data/lib/react_manifest/symbol_extractor.rb

@@ -44,6 +44,20 @@ module ReactManifest
       regex_extract_definitions(content)
     end
 
+    # Top-level const/let/class names of any casing (destructured ones included).
+    # These are the only declarations that throw when two classic scripts share a
+    # global lexical scope; var and function redeclaration is legal.
+    def extract_lexical_bindings(content, file_path: nil)
+      return [] unless content
+
+      if ast_engine_available?
+        result = AstExtractor.extract_lexical_bindings(content, file_path: file_path)
+        return result if result
+      end
+
+      regex_extract_lexical_bindings(content)
+    end
+
     def extract_usages(content, file_path: nil)
       return [] unless content
 
@@ -75,6 +89,19 @@ module ReactManifest
       symbols.uniq
     end
 
+    # ponytail: column-0 declarations only, flat destructuring; the AST path is exact.
+    def regex_extract_lexical_bindings(content)
+      names = content.scan(/^(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/).flatten
+      content.scan(/^(?:export\s+)?(?:const|let)\s+([A-Za-z_$][\w$]*)/) { |m| names << m[0] }
+      content.scan(/^(?:export\s+)?(?:const|let)\s*[{\[]([^}\]]*)[}\]]\s*=[^=]/) do |m|
+        m[0].split(",").each do |part|
+          name = part.split("=").first.split(":").last.to_s.sub("...", "").strip
+          names << name if name.match?(/\A[A-Za-z_$][\w$]*\z/)
+        end
+      end
+      names.uniq
+    end
+
     def regex_extract_usages(content)
       local_syms = Set.new
       DEFINITION_PATTERNS.each { |p| content.scan(p) { |m| local_syms << m[0] } }