jsx_rosetta 0.1.0

data/README.md

@@ -0,0 +1,328 @@
+# jsx_rosetta
+
+Translate React/JSX components into Rails 8.1 [ViewComponent](https://viewcomponent.org/)
+classes (or plain Rails view templates) — and lift React Router config into a
+runnable `rails generate controller` script.
+
+`jsx_rosetta` parses JSX/TSX via Babel running in a Node sidecar, lowers the
+parsed AST into a framework-agnostic semantic intermediate representation (IR), and emits target output
+through pluggable backends. The pipeline is end-to-end working: a real React
+app's components and routes can be translated, dropped into a fresh Rails 8.1
+app, and rendered with only a handful of human edits at the TODO markers the
+gem itself emits.
+
+```
+JSX text ──► Babel AST ──► Ruby AST ──► IR ──► backend ──► .rb / .html.erb / _controller.js
+            (Node sidecar) (typed tree) (sema)        (ViewComponent / RailsView / RoutesScript)
+```
+
+## Installation
+
+```bash
+bundle add jsx_rosetta
+bundle exec jsx_rosetta install   # npm-installs the gem's Node sidecar deps
+```
+
+Requires:
+- Ruby ≥ 3.2
+- Node.js ≥ 18 (subprocess used for parsing)
+
+The sidecar's `node_modules` is **not** bundled in the gem — `jsx_rosetta install`
+runs `npm install` in the gem's vendored `node/` directory. Set
+`JSX_ROSETTA_NODE` if `node` is in a non-standard location.
+
+## CLI
+
+```bash
+# Translate a JSX/TSX component into a ViewComponent (sidecar layout, default)
+jsx_rosetta translate path/to/Button.tsx -o app/components
+# →   app/components/button_component.rb
+#     app/components/button_component/button_component.html.erb
+#     app/components/button_component/button_controller.js   (when inline arrow handlers)
+
+# Translate a route-tied page as a Rails view template (no Ruby class)
+jsx_rosetta translate path/to/Home.tsx --as=view -o app/views/home
+# →   app/views/home/home.html.erb       (rename to index.html.erb)
+
+# Extract <Routes><Route> entries into a runnable Ruby script
+jsx_rosetta routes path/to/router.tsx -o tmp/generate_controllers.rb
+# Review the script. Uncomment the system() calls you want, then:
+ruby tmp/generate_controllers.rb
+
+# Inspect the parsed Babel AST
+jsx_rosetta parse path/to/Button.tsx > button.ast.json
+
+# Install the Node sidecar deps
+jsx_rosetta install
+
+jsx_rosetta version
+```
+
+`.tsx` files are auto-detected from the extension; pass `--tsx` to force
+TypeScript parsing on a `.jsx`-named file.
+
+## Library API
+
+```ruby
+require "jsx_rosetta"
+
+source = File.read("Button.tsx")
+
+# Just the parsed AST (Babel-shaped, typed Ruby objects)
+ast = JsxRosetta.parse(source)
+ast.walk.find { |n| n.is_a?(JsxRosetta::AST::JSXElement) }.tag_name
+# => "button"
+
+# Lowered IR (semantic, backend-agnostic). Returns the first component.
+ir = JsxRosetta.lower(source)
+ir.props.map(&:name)        # => ["children", "onClick", "variant"]
+ir.stimulus_methods         # event handlers extracted to Stimulus
+ir.react_hooks              # useState/useEffect/etc. flagged for the human
+
+# All components in a multi-component file
+JsxRosetta::IR.lower_all(JsxRosetta.parse(source), source: source)
+
+# End-to-end translation. Returns an array of File value objects.
+files = JsxRosetta.translate(source)
+files.first.path     # => "button_component.rb"
+files.first.contents # => "# frozen_string_literal: true\n…"
+
+# Same source as a plain Rails view (no .rb class, no sidecar dir)
+JsxRosetta.translate(source, backend: :rails_view)
+
+# Extract React Router routes
+route_tree = JsxRosetta::Routes.lower(JsxRosetta.parse(File.read("router.tsx")))
+JsxRosetta::Backend::RoutesScript.new(source_path: "router.tsx").emit(route_tree)
+```
+
+Optional kwargs to `JsxRosetta.translate`:
+- `backend: :view_component | :rails_view` (default `:view_component`)
+- `helpers: nil | Hash | false` — JSX-name → Rails-helper mapping (see below)
+- `layout: :sidecar | :flat` (default `:sidecar`, ignored for `:rails_view`)
+- `typescript: true` — force the TypeScript Babel plugin
+- `source_filename:` — surfaces in parse errors
+
+## What translates
+
+| JSX construct                        | Translation                                                |
+| ------------------------------------ | ---------------------------------------------------------- |
+| Function & arrow components          | `class XComponent < ::ViewComponent::Base`                 |
+| Multi-component files                | One `.rb` + `.html.erb` pair per exported component        |
+| `<button type="x">`                  | Literal HTML attribute                                     |
+| `<a href={url}>`                     | `href="<%= @url %>"` when `url` is a prop                  |
+| `<a href={`/p/${slug}`}>`            | `href="/p/<%= @slug %>"` (template literal inlined)        |
+| `<a aria-label={x}>`                 | `aria-label="<%= @x %>"` on Element; `"aria-label" => @x` on Component |
+| `<button type="button" {...rest}>`   | `<%= tag.button(type: "button", **@rest) do %>…<% end %>`  |
+| `<Button variant="primary" />`       | `<%= render ButtonComponent.new(variant: "primary") %>`    |
+| `<Tabs.List>`                        | `<%= render Tabs::ListComponent.new(...) %>`               |
+| `<Link href="/x">`                   | `<%= link_to("/x") do %>…<% end %>` (default helper map)   |
+| `<Image src="..." />`                | `<%= image_tag("...", alt: "...") %>` (default helper map) |
+| `{children}` (when prop)             | `<%= content %>` (ViewComponent default slot)              |
+| `{cond && <X />}`, `{cond ? X : Y}`  | `<% if %>…<% end %>` / with `<% else %>` branch            |
+| `{items.map((item, i) => <X />)}`    | `<% @items.each do \|item, i\| %>…<% end %>`               |
+| `{post.coverImage}`                  | `@post.cover_image` (member chains snake-cased)            |
+| `{!preview}`                         | `!@preview` (unary negation)                               |
+| `className={cn("a", b, { c: cond })}`| `class="a <%= @b %> <%= @cond ? "c" : '' %>"`              |
+| `style={{ fontSize: 12 }}`           | `style="font-size: 12;"` (kebab-case keys)                 |
+| `{/* foo */}`                        | `<%# foo %>`                                               |
+| `{"foo"}`, `{42}`                    | Plain text (`<%= " " %>` clutter eliminated)               |
+| `{true}`, `{null}`                   | Dropped (matches React runtime)                            |
+| `<hr />`, `<img />`                  | Self-closing void elements                                 |
+| `onClick={handler}` (handler is prop)| `data-action="<%= @handler %>"` (Stimulus action descriptor) |
+| `onClick={() => …}` (inline)         | Stimulus controller method + `data-action="click->name#methodName"` |
+| `const Comp = asChild ? X : "tag"`   | Synthesized `<% if @as_child %>…<% else %>…<% end %>`      |
+| Default values (`x = "primary"`)     | Translated when literal/identifier/member-chain            |
+| Bare prop identifiers                | `@snake_case_name`                                         |
+
+## What's flagged for human review
+
+The gem emits a `<%# TODO: … %>` comment whenever a translation isn't safe to
+auto-perform. Common cases:
+
+- **React hooks** (`useState`, `useEffect`, `useRef`, …) → distinct comment
+  block at the top of the template, with the Hotwire/Stimulus alternative
+  noted and the original JS preserved verbatim.
+- **Local non-JSX `const` bindings** (`const date = parseISO(s)`) → comment
+  block at the top with the original JS preserved.
+- **Unrecognized JS expressions** (function calls, subscripts, complex
+  ternaries) → inline TODO with verbatim source.
+- **Unresolved identifiers** (imports like `EXAMPLE_PATH`, `CMS_NAME`) →
+  inline TODO listing the offending names so the human can wire them up.
+- **`dangerouslySetInnerHTML` and similar opaque attributes** → flagged.
+- **Reserved Rails controller names** (in the routes script) → `# WARNING:`
+  line listing collisions.
+
+## What's deferred
+
+- Translating React state primitives (`useState` / `useEffect` etc.). The
+  policy is to flag and route behavior to Stimulus controllers, not to
+  recreate React's runtime in Ruby.
+- React Router's data-router form (`createBrowserRouter([...])`). Only the
+  declarative `<Routes><Route>` shape is parsed today.
+- Backends other than ViewComponent and RailsView (Phlex, Slim, LiveView).
+- Suspense → Turbo Frame mapping (depends on a data-fetching translation
+  story we don't have yet).
+
+## ViewComponent emission targets
+
+Two backends, picked via `--as` on the CLI or `backend:` in the API:
+
+**`:view_component` (default)** — emits a sidecar layout matching
+ViewComponent's `--sidecar` generator convention:
+
+```
+app/components/
+  card_component.rb                              # at top level
+  card_component/
+    card_component.html.erb                      # sidecar template
+    card_controller.js                           # Stimulus, when applicable
+```
+
+Pass `layout: :flat` to revert to the older flat layout
+(`card_component.rb` + `card_component.html.erb` side-by-side).
+
+**`:rails_view`** — for pages tied to a route. Emits one `.html.erb` with
+no Ruby class and no sidecar. Place at `app/views/<controller>/<action>.html.erb`;
+the controller's instance variables become the template's `@x` references.
+
+## Helper mappings
+
+Capitalized JSX tags that have a direct Rails helper analog skip the
+`<%= render XComponent.new(...) %>` indirection. Defaults:
+
+| JSX      | Emits                                          |
+| -------- | ---------------------------------------------- |
+| `<Link>` | `<%= link_to(href, **rest) do %>…<% end %>`    |
+| `<Image>`| `<%= image_tag(src, alt:, **rest) %>`          |
+
+Override:
+
+```ruby
+JsxRosetta.translate(source, helpers: {
+  "Link"  => { method: :link_to,   positional: :href },
+  "Image" => { method: :image_tag, positional: :src },
+  "Btn"   => { method: :button_to, positional: :url }
+})
+
+# Disable entirely (everything stays as <%= render XComponent.new(...) %>)
+JsxRosetta.translate(source, helpers: false)
+```
+
+## Stimulus integration
+
+Inline arrow event handlers (and const-bound arrows referenced from
+`onX={handler}`) extract to a generated `<snake>_controller.js` skeleton:
+
+```jsx
+function CopyButton({ text }) {
+  const handleClick = () => navigator.clipboard.writeText(text);
+  return <button onClick={handleClick}>Copy</button>;
+}
+```
+
+emits three files:
+
+```ruby
+# copy_button_component.rb
+class CopyButtonComponent < ::ViewComponent::Base
+  def initialize(text:); @text = text; end
+end
+```
+
+```erb
+<%# copy_button_component/copy_button_component.html.erb %>
+<button data-controller="copy-button"
+        data-action="click->copy-button#handleClick">
+  Copy
+</button>
+```
+
+```javascript
+// copy_button_component/copy_button_controller.js
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  // TODO: translate from the original JSX handler:
+  //   navigator.clipboard.writeText(text)
+  handleClick(event) {
+    // ...
+  }
+}
+```
+
+For Rails to find sidecar Stimulus controllers, add to
+`config/importmap.rb`:
+
+```ruby
+pin_all_from "app/components", under: "components", preload: true
+```
+
+and to `app/javascript/application.js`:
+
+```js
+import { application } from "controllers/application"
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("controllers", application)
+eagerLoadControllersFrom("components", application)
+```
+
+## Routes subcommand
+
+`jsx_rosetta routes router.tsx` parses `<Routes><Route>` JSX and emits a
+runnable Ruby script:
+
+- Lists each parsed `path → element` mapping.
+- Suggests `system "rails", "generate", "controller", …` invocations
+  (commented for review).
+- Consolidates `/xs` + `/xs/:id` pairs into `resources :xs, only: %i[index show]`.
+- Emits `match "*path", to: …, via: :all` for catch-all routes.
+- Warns when a generated controller name collides with a reserved Rails term.
+- Prints a suggested `config/routes.rb` block.
+
+The script is meant to be reviewed and edited before `ruby`-running it.
+
+## Architecture
+
+```
+lib/jsx_rosetta/
+  parser.rb                                # JSX text → AST::File
+  node_bridge.rb                           # subprocess plumbing
+  ast/                                     # typed Ruby classes mirroring Babel
+  ir/
+    types.rb                               # IR value classes
+    lowering.rb                            # AST → IR
+  routes.rb                                # AST → IR::RouteTree (React Router)
+  backend/
+    base.rb
+    view_component.rb                      # IR → .rb + .html.erb (+ _controller.js)
+    view_component/expression_translator.rb
+    rails_view.rb                          # IR → .html.erb only
+    routes_script.rb                       # IR::RouteTree → reviewable Ruby script
+  cli.rb                                   # exe/jsx_rosetta dispatch
+node/
+  parse.js                                 # stdin (JSX request) → stdout (Babel JSON AST)
+  package.json                             # @babel/parser
+```
+
+The IR sits between parsing and emission so additional backends (Phlex,
+Slim, LiveView, …) can be added without changing the frontend.
+
+## Development
+
+```bash
+bin/setup          # bundle install + npm install in node/
+bundle exec rspec  # run the full test suite
+bundle exec rubocop
+```
+
+End-to-end fixtures live in `spec/fixtures/`:
+- `spec/fixtures/jsx/*.{jsx,tsx}` — input JSX
+- `spec/fixtures/expected/*` — hand-written expected output
+
+For a worked example of dropping translated output into a real Rails 8.1 app,
+see `CHANGELOG.md` — Phase 9 and Phase 9b describe the multi-route React
+Router → Rails app demo end-to-end.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/jsx_rosetta

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jsx_rosetta"
+
+exit JsxRosetta::CLI.new(ARGV.dup).run

data/lib/jsx_rosetta/ast/inflector.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module JsxRosetta
+  module AST
+    # Internal helpers for converting between Babel's camelCase field names
+    # and Ruby's snake_case conventions.
+    module Inflector
+      module_function
+
+      def underscore(string)
+        string
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+      end
+
+      def camelize(string)
+        parts = string.split("_")
+        parts[0] + parts[1..].map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/ast/node.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "inflector"
+
+module JsxRosetta
+  module AST
+    # Base class for every Babel-shaped AST node. Wraps the raw JSON hash
+    # and provides:
+    #   * Field access via `node[:opening_element]` (snake_case symbols or
+    #     camelCase strings — both resolve to the same field).
+    #   * Source location accessors (`loc`, `range`, `start_pos`, `end_pos`).
+    #   * Tree traversal via `each_child` / `walk`.
+    #   * Pattern-matching support via `deconstruct_keys`.
+    #
+    # Specific Babel node types may register subclasses that add named
+    # accessors (e.g. JSXElement#opening_element). Unknown types fall
+    # through to the generic Node class so the parser doesn't crash on
+    # ESNext additions.
+    class Node
+      TYPE_REGISTRY = {} # rubocop:disable Style/MutableConstant
+
+      attr_reader :raw
+
+      def self.register(*type_names)
+        type_names.each { |name| TYPE_REGISTRY[name] = self }
+      end
+
+      def self.wrap(value)
+        case value
+        when Hash
+          if value.key?("type")
+            klass = TYPE_REGISTRY.fetch(value["type"], Node)
+            klass.new(value)
+          else
+            value
+          end
+        when Array
+          value.map { |element| wrap(element) }
+        else
+          value
+        end
+      end
+
+      def initialize(raw)
+        @raw = raw
+      end
+
+      def type
+        @raw["type"]
+      end
+
+      def loc
+        @raw["loc"]
+      end
+
+      def range
+        @raw["range"]
+      end
+
+      def start_pos
+        @raw["start"]
+      end
+
+      def end_pos
+        @raw["end"]
+      end
+
+      # Field access. Accepts snake_case symbols/strings (translated to
+      # camelCase) and camelCase strings (used verbatim).
+      def [](key)
+        raw_key = key.to_s
+        return Node.wrap(@raw[raw_key]) if @raw.key?(raw_key)
+
+        camel_key = Inflector.camelize(raw_key)
+        Node.wrap(@raw[camel_key])
+      end
+
+      def dig(*keys)
+        keys.reduce(self) do |current, key|
+          break nil if current.nil?
+
+          current[key]
+        end
+      end
+
+      def each_child(&block)
+        return enum_for(:each_child) unless block
+
+        @raw.each_value { |value| yield_descendant_nodes(value, &block) }
+      end
+
+      def children
+        each_child.to_a
+      end
+
+      def walk(&block)
+        return enum_for(:walk) unless block
+
+        yield self
+        each_child { |child| child.walk(&block) }
+      end
+
+      # Pattern-matching support. Returns a hash with snake_case symbol
+      # keys; values are wrapped (Node instances or arrays of Node/raw values).
+      def deconstruct_keys(keys)
+        if keys.nil?
+          @raw.each_with_object({}) do |(k, v), out|
+            out[Inflector.underscore(k).to_sym] = Node.wrap(v)
+          end
+        else
+          keys.each_with_object({}) do |key, out|
+            camel_key = Inflector.camelize(key.to_s)
+            actual_key = @raw.key?(key.to_s) ? key.to_s : camel_key
+            out[key] = Node.wrap(@raw[actual_key]) if @raw.key?(actual_key)
+          end
+        end
+      end
+
+      def ==(other)
+        other.is_a?(Node) && other.raw == @raw
+      end
+      alias eql? ==
+
+      def hash
+        @raw.hash
+      end
+
+      def inspect
+        "#<#{self.class.name || "JsxRosetta::AST::Node"} type=#{type.inspect} loc=#{loc_summary}>"
+      end
+
+      private
+
+      def yield_descendant_nodes(value, &block)
+        case value
+        when Hash
+          yield Node.wrap(value) if value.key?("type")
+        when Array
+          value.each { |element| yield_descendant_nodes(element, &block) }
+        end
+      end
+
+      def loc_summary
+        return "?" unless loc
+
+        start_loc = loc["start"] || {}
+        "#{start_loc["line"]}:#{start_loc["column"]}"
+      end
+    end
+  end
+end