react-manifest-rails 0.2.34 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0076f3ffaf1c303d4ac14a8345477b3851045267b0cba8f823f49ce5f17efa4f
-  data.tar.gz: 579d04e786fe515e46d9c56c5c755efcf616cfd49289fcef8ccda0cc4cce7fa8
+  metadata.gz: adc189b9603ad36c8d986e8f90cac383fcb65cfabafc60d64b3155681cd21ca7
+  data.tar.gz: 3cd94fbc6573c1548753ece80674a42d476619f7553b4fedffdd7d3b631cbe16
 SHA512:
-  metadata.gz: 6d221314836bc176da1378824e2ab7a55232d5977db2ca46b353d98f499b8e49d31b7999d0787953944db9c8b1c8652f3f17422918ee59d0fd5b78f5d46dca65
-  data.tar.gz: 3eeaba00d80ad2e7c73b1320026ea4b3ed0ed989b5a3c33513a2e45f6e63f7b632b466c2cb192e163b42892f4bce76b2dc59b87b90d90869c4eaa5137f4a8a86
+  metadata.gz: b382bb1ae0d2d9464402dbca4cacc0294897eea15e4a9a9917c447219ad8e5788ed22a2062d4dd2f28c7635c8e09ba2629972d8fc04a0e3b22d6769d87ec7a2c
+  data.tar.gz: f32f2baa961dbcb50b048191ed46e81f5ea7f016994355b2cba3a332b7f846e7f889df41cbc3fefb5364e8a7c3189484f3181058d825e6935ca6fc9ddced033e

data/CHANGELOG.md

@@ -7,6 +7,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- `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/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/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(',')}}"