jsx_rosetta 0.1.0

data/lib/jsx_rosetta/ir/types.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module JsxRosetta
+  module IR
+    # Marker module included by every IR node type. Lets backends and
+    # tests sanity-check that something is an IR value (`is_a?(IR::Node)`).
+    module Node
+    end
+
+    # A translated component definition. The root of a lowered IR tree.
+    #
+    # name           : String — component name as it appears in JSX (e.g. "Button").
+    # props          : [Prop]
+    # body           : Node — usually an Element or Fragment.
+    # rest_prop_name : String | nil — name of a rest-destructured prop
+    #                  (`function X({ a, ...rest })`). When non-nil, the
+    #                  backend should generate a `**rest` initializer kwarg
+    #                  and make it available via `@rest_prop_name`.
+    # local_bindings : [LocalBinding] — non-JSX local `const` bindings inside
+    #                  the component body. Backends typically render these as
+    #                  a TODO comment block since arbitrary JS-to-Ruby
+    #                  translation isn't attempted.
+    # stimulus_methods : [StimulusMethod] — event handlers extracted from
+    #                  inline arrows / const-bound arrows used in onX={...}.
+    #                  When non-empty, backends should emit a sibling
+    #                  Stimulus controller file alongside the .rb/.erb pair.
+    # react_hooks    : [ReactHookCall] — calls to React hooks (useState,
+    #                  useEffect, useRef, useContext, useMemo, useCallback,
+    #                  useReducer, useImperativeHandle, useLayoutEffect).
+    #                  Surfaced as a distinct TODO block so the human
+    #                  reviewer knows to translate behavior to Stimulus
+    #                  and state to server-side rendering.
+    Component = Data.define(:name, :props, :body, :rest_prop_name,
+                            :local_bindings, :stimulus_methods, :react_hooks) do
+      include Node
+    end
+
+    # A non-JSX local binding declared inside the component body
+    # (`const date = parseISO(dateString)`). The verbatim source is
+    # preserved so the human reviewer can translate it.
+    #
+    # name   : String
+    # source : String — verbatim JS of the entire VariableDeclaration statement.
+    LocalBinding = Data.define(:name, :source) do
+      include Node
+    end
+
+    # A React hook invocation detected in the component body (`useState`,
+    # `useEffect`, …). Surfaced separately from local_bindings so backends
+    # can emit a more specific TODO that points at the Stimulus / Hotwire
+    # / server-render alternative, instead of a generic "translate this JS".
+    #
+    # hook   : String — hook function name (`"useState"`, `"useEffect"`, …)
+    # source : String — verbatim JS of the entire statement.
+    ReactHookCall = Data.define(:hook, :source) do
+      include Node
+    end
+
+    # A component prop, possibly with a default value.
+    #
+    # name    : String
+    # default : Interpolation | nil
+    Prop = Data.define(:name, :default) do
+      include Node
+    end
+
+    # An HTML element (lowercase tag name, no member-expression form).
+    #
+    # tag        : String — "button", "div", etc.
+    # attributes : [Attribute | StyleBinding] (and EventBinding once Phase 4 lands)
+    # children   : [Element | ComponentInvocation | Text | Interpolation | Fragment]
+    Element = Data.define(:tag, :attributes, :children) do
+      include Node
+    end
+
+    # A component invocation. Distinct from Element so backends can render
+    # it as `render Component.new(...)` rather than as a raw HTML tag.
+    #
+    # name     : String — "Button", "Foo.Bar", etc.
+    # props    : [Attribute | StyleBinding]
+    # children : [Element | ComponentInvocation | Text | Interpolation | Fragment]
+    ComponentInvocation = Data.define(:name, :props, :children) do
+      include Node
+    end
+
+    # A spread attribute: `{...rest}` in JSX. The expression is preserved
+    # verbatim; backends emit it as `**<expression>` or equivalent.
+    #
+    # expression : String — verbatim JS source of the spread argument
+    #              (typically a single identifier, sometimes a member chain).
+    SpreadAttribute = Data.define(:expression) do
+      include Node
+    end
+
+    # A name/value pair on an Element or ComponentInvocation.
+    #
+    # name  : String
+    # value : String | true | Interpolation
+    #         - String: literal value from a JSX string-literal attribute
+    #           (e.g. `type="button"` → value: "button").
+    #         - true: boolean attribute with no value (e.g. `<input disabled />`).
+    #         - Interpolation: expression-container value (e.g. `href={url}`).
+    Attribute = Data.define(:name, :value) do
+      include Node
+    end
+
+    # A class-binding expression — what JSX expresses as `className={...}`.
+    #
+    # expression : String — verbatim JS source of the className value
+    #                       (literal string in quotes, template literal,
+    #                       call to `cn(...)`, etc.). Decomposition into
+    #                       individual classes/conditionals is deferred.
+    StyleBinding = Data.define(:expression) do
+      include Node
+    end
+
+    # A decomposed className expression — the result of recognizing a
+    # `cn(...)` / `clsx(...)` / `classnames(...)` call at lowering time.
+    # Each segment is one of:
+    #   String                 — literal class chunk like "btn btn-primary"
+    #   Interpolation          — variable reference (translated by backend)
+    #   ConditionalSegment     — `{ "active": isActive }` style entry
+    ClassList = Data.define(:segments) do
+      include Node
+    end
+
+    # A conditional class entry (`{ "active": isActive }` from cn-style
+    # helpers). Renders the class_name when the condition is truthy.
+    #
+    # class_name : String — literal class string to emit when condition is truthy.
+    # condition  : Interpolation — verbatim JS source of the condition.
+    ConditionalSegment = Data.define(:class_name, :condition) do
+      include Node
+    end
+
+    # A decomposed inline-style expression (JSX `style={{ ... }}`).
+    #
+    # declarations : [StyleDeclaration] — one per property in the source order
+    Style = Data.define(:declarations) do
+      include Node
+    end
+
+    # A single CSS property/value pair, with the property already converted
+    # from JSX camelCase to CSS kebab-case.
+    #
+    # property : String — kebab-case CSS property (e.g. "font-size")
+    # value    : String | Interpolation — String for literal CSS values
+    #            already quoted ready for output, Interpolation for runtime
+    #            values to be ERB-interpolated.
+    StyleDeclaration = Data.define(:property, :value) do
+      include Node
+    end
+
+    # An opaque JS expression embedded in JSX (between curlies). The
+    # expression text is preserved verbatim so the backend can emit it
+    # into `<%= %>` (or its target equivalent) for human review.
+    #
+    # expression : String — verbatim JS source.
+    Interpolation = Data.define(:expression) do
+      include Node
+    end
+
+    # A literal text node.
+    #
+    # value : String
+    Text = Data.define(:value) do
+      include Node
+    end
+
+    # A comment lifted from JSX (`{/* … */}`). Backends decide how to
+    # surface it (ERB `<%# … %>`, HTML `<!-- -->`, etc.).
+    #
+    # text : String — comment body verbatim, including any leading/trailing
+    #                 whitespace from the JSX source.
+    Comment = Data.define(:text) do
+      include Node
+    end
+
+    # A JSX fragment (`<>...</>`).
+    #
+    # children : [Element | ComponentInvocation | Text | Interpolation | Fragment]
+    Fragment = Data.define(:children) do
+      include Node
+    end
+
+    # A conditional render. Lowered from any of:
+    #   {cond && <X />}
+    #   {cond ? <X /> : null}
+    #   {cond ? <X /> : <Y />}
+    #
+    # test       : Interpolation — verbatim JS source of the condition.
+    # consequent : Node — what to render when test is truthy.
+    # alternate  : Node | nil — what to render otherwise (nil for `cond &&`
+    #              or for `cond ? X : null`).
+    Conditional = Data.define(:test, :consequent, :alternate) do
+      include Node
+    end
+
+    # A content slot. Backends decide how to realize it (ViewComponent's
+    # `content` for the default slot, named renders_one slots for others).
+    #
+    # name : String — "children" for the default slot, or a prop name.
+    Slot = Data.define(:name) do
+      include Node
+    end
+
+    # An event handler binding. Lowered from a JSX attribute named
+    # `on<Event>` whose value is an expression container.
+    #
+    # event   : String — lowercased DOM event name ("click", "change",
+    #           "mouseenter").
+    # handler : Interpolation — the JS expression bound to the event,
+    #           verbatim. For ViewComponent + Stimulus, the caller is
+    #           expected to supply a Stimulus action descriptor string
+    #           (e.g. "click->my-controller#handleClick"); the component
+    #           just renders it through.
+    EventBinding = Data.define(:event, :handler) do
+      include Node
+    end
+
+    # An event handler routed through a generated Stimulus controller.
+    #
+    # event       : String — lowercased DOM event name.
+    # method_name : String — Stimulus controller method (camelCase per
+    #               Stimulus convention).
+    StimulusBinding = Data.define(:event, :method_name) do
+      include Node
+    end
+
+    # A flat list of React Router routes parsed from a router file.
+    # Distinct from Component — RouteTree is the top-level result of
+    # `JsxRosetta::Routes.lower(file)`, not part of a translated component.
+    #
+    # routes : [RouteEntry]
+    RouteTree = Data.define(:routes) do
+      include Node
+    end
+
+    # A single React Router route entry.
+    #
+    # path         : String — the JSX path attribute verbatim (e.g. "/posts/:id").
+    # element_name : String — the JSX element name from element={<X />}
+    #                (e.g. "PostShow"). Member-expression forms ("Layout.Index")
+    #                are flattened to the rightmost name.
+    RouteEntry = Data.define(:path, :element_name) do
+      include Node
+    end
+
+    # A handler method to be emitted on the generated Stimulus controller.
+    # Body translation is deferred to the human reviewer; we preserve the
+    # original JS body verbatim.
+    #
+    # name        : String — camelCase Stimulus method name.
+    # body_source : String — verbatim JS body (the entire arrow function or
+    #               the function expression body), preserved as a comment in
+    #               the emitted controller skeleton.
+    StimulusMethod = Data.define(:name, :body_source) do
+      include Node
+    end
+
+    # A list-rendering loop. Lowered from a JSX expression of the form:
+    #   {items.map((item) => <X />)}
+    #   {items.map((item, index) => <X />)}
+    # plus the arrow-with-block form `(item) => { return <X />; }`.
+    #
+    # iterable      : Interpolation — verbatim source of the iterable
+    #                 expression (e.g. "items", "todos.filter(...)").
+    # item_binding  : String — name of the item parameter, in original
+    #                 camelCase. Backends snake_case as needed.
+    # index_binding : String | nil — name of the index parameter, if present.
+    # body          : Node — the lowered IR node rendered for each iteration.
+    Loop = Data.define(:iterable, :item_binding, :index_binding, :body) do
+      include Node
+    end
+  end
+end

data/lib/jsx_rosetta/ir.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "ir/types"
+require_relative "ir/lowering"
+
+module JsxRosetta
+  module IR
+    def self.lower(ast_file, source:)
+      Lowering.lower(ast_file, source: source)
+    end
+
+    def self.lower_all(ast_file, source:)
+      Lowering.lower_all(ast_file, source: source)
+    end
+  end
+end

data/lib/jsx_rosetta/node_bridge.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module JsxRosetta
+  # Spawns the Node sidecar (`node/parse.js`) as a one-shot subprocess
+  # per parse request. A long-lived worker is a future optimization.
+  class NodeBridge
+    SIDECAR_DIR = File.expand_path("../../node", __dir__)
+    SIDECAR_SCRIPT = File.join(SIDECAR_DIR, "parse.js")
+    NODE_MODULES_DIR = File.join(SIDECAR_DIR, "node_modules")
+
+    class MissingNode < Error; end
+    class MissingDependencies < Error; end
+
+    def parse(source, typescript: false, source_filename: nil)
+      ensure_dependencies_installed!
+
+      request = JSON.generate(
+        source: source,
+        typescript: typescript,
+        source_filename: source_filename
+      )
+      stdout, stderr, status = Open3.capture3(node_executable, SIDECAR_SCRIPT, stdin_data: request)
+
+      raise Error, "jsx_rosetta sidecar exited with status #{status.exitstatus}: #{stderr.strip}" unless status.success?
+
+      JSON.parse(stdout)
+    rescue Errno::ENOENT
+      raise MissingNode, missing_node_message
+    end
+
+    private
+
+    def node_executable
+      ENV["JSX_ROSETTA_NODE"] || "node"
+    end
+
+    def ensure_dependencies_installed!
+      return if File.directory?(File.join(NODE_MODULES_DIR, "@babel", "parser"))
+
+      raise MissingDependencies, <<~MSG.strip
+        Node dependencies for jsx_rosetta are not installed.
+        Run `bundle exec jsx_rosetta install` (or `cd #{SIDECAR_DIR} && npm install`).
+      MSG
+    end
+
+    def missing_node_message
+      <<~MSG.strip
+        Could not find Node.js. jsx_rosetta requires Node.js (>= 18) on PATH,
+        or set JSX_ROSETTA_NODE to the absolute path of a node executable.
+      MSG
+    end
+  end
+end

data/lib/jsx_rosetta/parse_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JsxRosetta
+  class ParseError < Error
+    attr_reader :line, :column
+
+    def initialize(message, line: nil, column: nil)
+      super(message)
+      @line = line
+      @column = column
+    end
+
+    def to_s
+      return super if line.nil?
+
+      "#{super} (#{line}:#{column})"
+    end
+  end
+end

data/lib/jsx_rosetta/parser.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+require_relative "node_bridge"
+require_relative "parse_error"
+
+module JsxRosetta
+  # Public entry point for JSX → AST parsing.
+  #
+  # Returns a typed AST::Node tree (rooted at AST::File) that mirrors the
+  # Babel AST shape with Ruby ergonomics: snake_case field accessors,
+  # source location preservation, traversal helpers, and pattern-matching
+  # support.
+  class Parser
+    def initialize(node_bridge: NodeBridge.new)
+      @node_bridge = node_bridge
+    end
+
+    def parse(source, typescript: false, source_filename: nil)
+      response = @node_bridge.parse(source, typescript: typescript, source_filename: source_filename)
+
+      if response["ok"]
+        AST.build(response["ast"])
+      else
+        error = response["error"] || {}
+        raise ParseError.new(error["message"] || "JSX parse failed", line: error["line"], column: error["column"])
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/routes.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "ir/types"
+
+module JsxRosetta
+  # React Router → IR::RouteTree extraction. Recognizes the JSX-based
+  # declarative form (<Routes><Route path="..." element={<X />} /></Routes>)
+  # and the bare `<Route path="..." element={<X />} />` form anywhere in
+  # the AST. The data-router form (createBrowserRouter([{ path, element }]))
+  # is a future addition.
+  module Routes
+    def self.lower(ast_file)
+      Lowering.new.lower(ast_file)
+    end
+
+    class Lowering
+      def lower(ast_file)
+        routes = []
+        ast_file.walk do |node|
+          next unless node.is_a?(AST::JSXElement)
+          next unless node.tag_name == "Route"
+
+          path = extract_path(node)
+          element_name = extract_element_name(node)
+          next if path.nil? || element_name.nil?
+
+          routes << IR::RouteEntry.new(path: path, element_name: element_name)
+        end
+        IR::RouteTree.new(routes: routes)
+      end
+
+      private
+
+      def find_attribute(element, name)
+        element.opening_element.attributes.find do |attr|
+          attr.is_a?(AST::JSXAttribute) && attr.attribute_name == name
+        end
+      end
+
+      def extract_path(element)
+        attr = find_attribute(element, "path")
+        return nil unless attr
+
+        value = attr.value
+        case value
+        when nil
+          nil
+        when AST::JSXExpressionContainer
+          inner = value.expression
+          inner.type == "StringLiteral" ? inner[:value] : nil
+        else
+          value.raw["value"] if value.raw["type"] == "StringLiteral"
+        end
+      end
+
+      def extract_element_name(element)
+        attr = find_attribute(element, "element")
+        return nil unless attr.is_a?(AST::JSXAttribute)
+        return nil unless attr.value.is_a?(AST::JSXExpressionContainer)
+
+        inner = attr.value.expression
+        return nil unless inner.is_a?(AST::JSXElement)
+
+        flatten_element_name(inner.tag_name)
+      end
+
+      def flatten_element_name(tag_name)
+        tag_name.to_s.split(".").last
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JsxRosetta
+  VERSION = "0.1.0"
+end

data/lib/jsx_rosetta.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "jsx_rosetta/version"
+
+module JsxRosetta
+  class Error < StandardError; end
+
+  def self.parse(source, typescript: false, source_filename: nil)
+    Parser.new.parse(source, typescript: typescript, source_filename: source_filename)
+  end
+
+  def self.lower(source, typescript: false, source_filename: nil)
+    ast = parse(source, typescript: typescript, source_filename: source_filename)
+    IR.lower(ast, source: source)
+  end
+
+  def self.translate(source, backend: :view_component, helpers: nil, layout: :sidecar,
+                     typescript: false, source_filename: nil)
+    ast = parse(source, typescript: typescript, source_filename: source_filename)
+    components = IR.lower_all(ast, source: source)
+    backend_instance = backend_for(backend, helpers: helpers, layout: layout)
+    components.flat_map { |component| backend_instance.emit(component) }
+  end
+
+  def self.backend_for(name, helpers: nil, layout: :sidecar)
+    case name
+    when :view_component then Backend::ViewComponent.new(helpers: helpers, layout: layout)
+    when :rails_view then Backend::RailsView.new(helpers: helpers, layout: layout)
+    else
+      raise Error, "unknown backend: #{name.inspect}"
+    end
+  end
+end
+
+require_relative "jsx_rosetta/parse_error"
+require_relative "jsx_rosetta/node_bridge"
+require_relative "jsx_rosetta/parser"
+require_relative "jsx_rosetta/ir"
+require_relative "jsx_rosetta/routes"
+require_relative "jsx_rosetta/backend"
+require_relative "jsx_rosetta/cli"

data/node/.gitignore

@@ -0,0 +1 @@
+node_modules/

data/node/package-lock.json

@@ -0,0 +1,64 @@
+{
+  "name": "jsx_rosetta-sidecar",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "jsx_rosetta-sidecar",
+      "version": "0.1.0",
+      "dependencies": {
+        "@babel/parser": "^7.25.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@babel/helper-string-parser": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
+      "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz",
+      "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/parser": {
+      "version": "7.29.3",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.3.tgz",
+      "integrity": "sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.29.0"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@babel/types": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
+      "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^7.27.1",
+        "@babel/helper-validator-identifier": "^7.28.5"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    }
+  }
+}

data/node/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "jsx_rosetta-sidecar",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Node sidecar for the jsx_rosetta Ruby gem. Parses JSX/TSX via @babel/parser and returns the AST as JSON.",
+  "main": "parse.js",
+  "scripts": {
+    "parse": "node parse.js"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.25.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

data/node/parse.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// jsx_rosetta Node sidecar.
+//
+// Reads a JSON request from stdin, parses the source with @babel/parser,
+// and writes a JSON response to stdout.
+//
+// Request:  { "source": "...", "typescript": false, "source_filename": "..." }
+// Response (success): { "ok": true, "ast": <Babel File node> }
+// Response (failure): { "ok": false, "error": { "message", "line", "column" } }
+//
+// Errors during stdin read or JSON parse exit with a non-zero status and
+// print the error message to stderr.
+
+"use strict";
+
+const { parse } = require("@babel/parser");
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", reject);
+  });
+}
+
+function buildPlugins(typescript) {
+  const plugins = ["jsx"];
+  if (typescript) plugins.push("typescript");
+  return plugins;
+}
+
+async function main() {
+  const raw = await readStdin();
+  let request;
+  try {
+    request = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`jsx_rosetta sidecar: invalid JSON request: ${e.message}\n`);
+    process.exit(2);
+  }
+
+  const source = request.source ?? "";
+  const typescript = Boolean(request.typescript);
+  const sourceFilename = request.source_filename;
+
+  try {
+    const ast = parse(source, {
+      sourceType: "module",
+      sourceFilename,
+      allowImportExportEverywhere: true,
+      allowReturnOutsideFunction: true,
+      plugins: buildPlugins(typescript),
+      tokens: false,
+      ranges: true,
+    });
+    process.stdout.write(JSON.stringify({ ok: true, ast }));
+  } catch (err) {
+    const response = {
+      ok: false,
+      error: {
+        message: err.message,
+        line: err.loc ? err.loc.line : null,
+        column: err.loc ? err.loc.column : null,
+      },
+    };
+    process.stdout.write(JSON.stringify(response));
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`jsx_rosetta sidecar: unexpected error: ${err && err.stack ? err.stack : err}\n`);
+  process.exit(1);
+});