jsx_rosetta 0.1.0

data/lib/jsx_rosetta/ast/types.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require_relative "node"
+
+module JsxRosetta
+  module AST
+    # Subclasses for the Babel node types where named accessors carry their
+    # weight (mostly the JSX subtree). Other Babel types fall through to the
+    # generic Node class — they're still walkable, pattern-matchable, and
+    # field-addressable, just without bespoke methods.
+    #
+    # As lowering passes need more ergonomic access to specific node fields,
+    # add a class here. Don't pre-emptively wrap every Babel type.
+
+    class File < Node
+      register "File"
+
+      def program
+        self[:program]
+      end
+    end
+
+    class Program < Node
+      register "Program"
+
+      def body
+        self[:body]
+      end
+
+      def source_type
+        @raw["sourceType"]
+      end
+    end
+
+    class JSXElement < Node
+      register "JSXElement"
+
+      def opening_element
+        self[:opening_element]
+      end
+
+      def closing_element
+        self[:closing_element]
+      end
+
+      def jsx_children
+        self[:children]
+      end
+
+      def tag_name
+        opening_element&.tag_name
+      end
+
+      def self_closing?
+        opening_element&.self_closing? || false
+      end
+    end
+
+    class JSXOpeningElement < Node
+      register "JSXOpeningElement"
+
+      def name
+        self[:name]
+      end
+
+      def attributes
+        self[:attributes]
+      end
+
+      def tag_name
+        node_to_tag_name(name)
+      end
+
+      def self_closing?
+        @raw["selfClosing"] == true
+      end
+
+      private
+
+      def node_to_tag_name(node)
+        case node
+        when JSXIdentifier then node.name
+        when JSXMemberExpression, JSXNamespacedName then node.qualified_name
+        end
+      end
+    end
+
+    class JSXClosingElement < Node
+      register "JSXClosingElement"
+
+      def name
+        self[:name]
+      end
+    end
+
+    class JSXIdentifier < Node
+      register "JSXIdentifier"
+
+      def name
+        @raw["name"]
+      end
+    end
+
+    class JSXMemberExpression < Node
+      register "JSXMemberExpression"
+
+      def object
+        self[:object]
+      end
+
+      def property
+        self[:property]
+      end
+
+      def qualified_name
+        "#{object_name}.#{property.name}"
+      end
+
+      private
+
+      def object_name
+        case object
+        when JSXIdentifier then object.name
+        when JSXMemberExpression then object.qualified_name
+        end
+      end
+    end
+
+    class JSXNamespacedName < Node
+      register "JSXNamespacedName"
+
+      def namespace
+        self[:namespace]
+      end
+
+      def name
+        self[:name]
+      end
+
+      def qualified_name
+        "#{namespace.name}:#{name.name}"
+      end
+    end
+
+    class JSXAttribute < Node
+      register "JSXAttribute"
+
+      def name
+        self[:name]
+      end
+
+      def value
+        self[:value]
+      end
+
+      def attribute_name
+        case (attr_name = name)
+        when JSXIdentifier then attr_name.name
+        when JSXNamespacedName then attr_name.qualified_name
+        end
+      end
+    end
+
+    class JSXSpreadAttribute < Node
+      register "JSXSpreadAttribute"
+
+      def argument
+        self[:argument]
+      end
+    end
+
+    class JSXExpressionContainer < Node
+      register "JSXExpressionContainer"
+
+      def expression
+        self[:expression]
+      end
+    end
+
+    class JSXSpreadChild < Node
+      register "JSXSpreadChild"
+
+      def expression
+        self[:expression]
+      end
+    end
+
+    class JSXText < Node
+      register "JSXText"
+
+      def value
+        @raw["value"]
+      end
+    end
+
+    class JSXEmptyExpression < Node
+      register "JSXEmptyExpression"
+    end
+
+    class JSXFragment < Node
+      register "JSXFragment"
+
+      def opening_fragment
+        self[:opening_fragment]
+      end
+
+      def closing_fragment
+        self[:closing_fragment]
+      end
+
+      def jsx_children
+        self[:children]
+      end
+    end
+
+    class JSXOpeningFragment < Node
+      register "JSXOpeningFragment"
+    end
+
+    class JSXClosingFragment < Node
+      register "JSXClosingFragment"
+    end
+  end
+end

data/lib/jsx_rosetta/ast/visitor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "inflector"
+require_relative "node"
+
+module JsxRosetta
+  module AST
+    # Visitor base class. Subclasses define `visit_<snake_case_type>`
+    # methods to handle specific Babel node types. Anything without a
+    # dedicated handler falls through to `visit_default`, which by default
+    # recurses into the node's children.
+    #
+    # Example:
+    #   class TagCollector < JsxRosetta::AST::Visitor
+    #     attr_reader :tags
+    #     def initialize; @tags = []; super; end
+    #
+    #     def visit_jsx_element(node)
+    #       @tags << node.tag_name
+    #       visit_children(node)
+    #     end
+    #   end
+    #
+    #   collector = TagCollector.new
+    #   collector.visit(parsed_file)
+    class Visitor
+      def visit(node)
+        return unless node.is_a?(Node)
+
+        method_name = "visit_#{Inflector.underscore(node.type)}"
+        if respond_to?(method_name)
+          public_send(method_name, node)
+        else
+          visit_default(node)
+        end
+      end
+
+      def visit_default(node)
+        visit_children(node)
+      end
+
+      def visit_children(node)
+        node.each_child { |child| visit(child) }
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/ast.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "ast/inflector"
+require_relative "ast/node"
+require_relative "ast/types"
+require_relative "ast/visitor"
+
+module JsxRosetta
+  module AST
+    # Wrap a parsed Babel JSON tree (Hash) into typed AST::Node objects.
+    def self.build(json_hash)
+      Node.wrap(json_hash)
+    end
+  end
+end

data/lib/jsx_rosetta/backend/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module JsxRosetta
+  module Backend
+    # Backends consume an IR::Component and emit one or more output files.
+    # The return value is an array of File value objects so callers can
+    # decide whether to write to disk, return as strings, or compare
+    # against a golden fixture.
+    class Base
+      # A single file produced by a backend.
+      #
+      #   path     : String — relative output path (e.g. "button_component.rb").
+      #   contents : String — the file body.
+      File = Data.define(:path, :contents)
+
+      def emit(_ir_component)
+        raise NotImplementedError, "#{self.class} must implement #emit"
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/backend/rails_view.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "view_component"
+
+module JsxRosetta
+  module Backend
+    # Emits a translated component as a plain Rails view template
+    # (`<snake>.html.erb`) instead of a ViewComponent class + sidecar
+    # template. Pages tied to routes are conceptually Rails views, not
+    # reusable components — the controller sets `@instance_variables` and
+    # the template uses them directly.
+    #
+    # Reuses the ViewComponent backend's IR-rendering pipeline; only the
+    # output shape differs (no Ruby class, no sidecar directory). When the
+    # source JSX includes inline event handlers, a Stimulus controller is
+    # still emitted as a sibling file alongside the .html.erb.
+    class RailsView < ViewComponent
+      def emit(component)
+        prop_names = component.props.map(&:name)
+        prop_names << component.rest_prop_name if component.rest_prop_name
+        translator = ExpressionTranslator.new(prop_names: prop_names)
+
+        @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
+
+        files = [
+          File.new(
+            path: "#{AST::Inflector.underscore(component.name)}.html.erb",
+            contents: render_erb_template(component, translator)
+          )
+        ]
+        if component.stimulus_methods.any?
+          files << File.new(
+            path: "#{AST::Inflector.underscore(component.name)}_controller.js",
+            contents: render_stimulus_controller_js(component)
+          )
+        end
+        files
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/backend/routes_script.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative "../ast/inflector"
+
+module JsxRosetta
+  module Backend
+    # Emits a reviewable Ruby script from an IR::RouteTree.
+    #
+    # The output prints the parsed routes, lists `system "rails", "generate",
+    # "controller", ...` invocations (commented out by default), and a
+    # suggested config/routes.rb block. The user is expected to review the
+    # script, uncomment the commands they want to run, and execute it with
+    # `ruby <output>.rb`.
+    class RoutesScript
+      RESERVED_CONTROLLER_NAMES = %w[application action rails].freeze
+
+      def initialize(source_path: nil, generated_at: Time.now.utc.strftime("%Y-%m-%d"))
+        @source_path = source_path
+        @generated_at = generated_at
+      end
+
+      def emit(route_tree)
+        lines = header_lines + body_lines(route_tree)
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def header_lines
+        provenance = @source_path ? "from #{@source_path}" : ""
+        [
+          "#!/usr/bin/env ruby",
+          "# frozen_string_literal: true",
+          "#",
+          "# Generated by jsx_rosetta routes #{provenance} on #{@generated_at}.",
+          "# Review this script. Uncomment the system() calls you want to run,",
+          "# then execute with `ruby <this-file>`.",
+          ""
+        ]
+      end
+
+      def body_lines(route_tree)
+        return ["puts 'No <Route> entries were recognized.'"] if route_tree.routes.empty?
+
+        groups = group_routes(route_tree.routes)
+        routes_array_lines(route_tree.routes) +
+          [""] +
+          report_lines +
+          [""] +
+          generator_lines(groups) +
+          [""] +
+          routes_dsl_lines(groups)
+      end
+
+      # Group routes that share a resource shape so they can be emitted as
+      # `resources :plural, only: %i[index show]` instead of two siloed
+      # `get` lines. Returns an array where each element is either a Hash
+      # `{ kind: :resource, plural:, actions: }` or `{ kind: :route, route: }`.
+      def group_routes(routes)
+        buckets, ungrouped = bucket_routes_by_resource(routes)
+        groups = []
+        buckets.each do |plural, by_action|
+          if resource_pair?(by_action)
+            groups << { kind: :resource, plural: plural, actions: by_action.keys }
+          else
+            by_action.each_value { |route| ungrouped << route }
+          end
+        end
+        ungrouped.each { |route| groups << { kind: :route, route: route } }
+        groups
+      end
+
+      def bucket_routes_by_resource(routes)
+        # Build buckets keyed by plural noun (`/posts` and `/posts/:id` both map to `posts`).
+        buckets = Hash.new { |h, k| h[k] = {} }
+        ungrouped = []
+        routes.each do |route|
+          shape = resource_shape(route.path)
+          shape ? (buckets[shape[:plural]][shape[:action]] = route) : ungrouped << route
+        end
+        [buckets, ungrouped]
+      end
+
+      def resource_pair?(by_action)
+        by_action.size >= 2 && (by_action.keys & %w[index show]).size == 2
+      end
+
+      def resource_shape(path)
+        if (m = %r{\A/(?<plural>[a-z][a-z0-9_-]*)\z}.match(path))
+          { plural: m[:plural], action: "index" }
+        elsif (m = %r{\A/(?<plural>[a-z][a-z0-9_-]*)/:(?<param>[a-z_][a-z0-9_]*)\z}.match(path))
+          { plural: m[:plural], action: "show" }
+        end
+      end
+
+      def routes_array_lines(routes)
+        ["routes = ["] +
+          routes.map { |r| "  { path: #{r.path.inspect}, element: #{r.element_name.inspect} }," } +
+          ["]"]
+      end
+
+      def report_lines
+        [
+          %(puts "Parsed routes:"),
+          %(routes.each { |r| puts "  \#{r[:path]} → \#{r[:element]}" })
+        ]
+      end
+
+      def generator_lines(groups)
+        controllers = collect_controller_names(groups)
+        warning = collision_warning(controllers)
+        lines = ["# Run these by uncommenting the lines you want:"]
+        lines << warning if warning
+        groups.each { |group| lines << generator_line_for(group) }
+        lines
+      end
+
+      def generator_line_for(group)
+        if group[:kind] == :resource
+          plural = group[:plural]
+          %(# system "rails", "generate", "controller", "#{plural}", "index", "show", "--skip-routes")
+        else
+          route = group[:route]
+          controller = AST::Inflector.underscore(route.element_name)
+          action = action_for_path(route.path)
+          %(# system "rails", "generate", "controller", "#{controller}", "#{action}", "--skip-routes")
+        end
+      end
+
+      def routes_dsl_lines(groups)
+        body = groups.flat_map { |group| group_to_dsl_lines(group) }
+        [
+          "puts <<~RB",
+          "",
+          "  # Suggested config/routes.rb additions:",
+          "  Rails.application.routes.draw do"
+        ] + body + [
+          "  end",
+          "RB"
+        ]
+      end
+
+      def group_to_dsl_lines(group)
+        if group[:kind] == :resource
+          ["      resources :#{group[:plural]}, only: %i[#{group[:actions].sort.join(" ")}]"]
+        else
+          [route_to_dsl_line(group[:route])]
+        end
+      end
+
+      def route_to_dsl_line(route)
+        controller = AST::Inflector.underscore(route.element_name)
+        action = action_for_path(route.path)
+        path = normalize_catch_all(route.path)
+        if catch_all?(route.path)
+          %(      match #{path.inspect}, to: "#{controller}##{action}", via: :all)
+        else
+          %(      get #{path.inspect}, to: "#{controller}##{action}")
+        end
+      end
+
+      def action_for_path(path)
+        path.match?(/:[a-zA-Z_]/) ? "show" : "index"
+      end
+
+      def catch_all?(path)
+        path.start_with?("*")
+      end
+
+      # Rails routing requires a name for splat segments. A bare `*` from
+      # JSX (`<Route path="*" />`) is illegal; normalize to `*path`.
+      def normalize_catch_all(path)
+        path == "*" ? "*path" : path
+      end
+
+      def collect_controller_names(groups)
+        groups.flat_map do |group|
+          group[:kind] == :resource ? [group[:plural]] : [AST::Inflector.underscore(group[:route].element_name)]
+        end
+      end
+
+      def collision_warning(controllers)
+        collisions = controllers & RESERVED_CONTROLLER_NAMES
+        return nil if collisions.empty?
+
+        "# WARNING: these controller names collide with Rails reserved terms; " \
+          "rename before running: #{collisions.join(", ")}"
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/backend/view_component/expression_translator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../../ast/inflector"
+
+module JsxRosetta
+  module Backend
+    class ViewComponent
+      # Best-effort, narrowly-scoped JS-to-Ruby translation for the simple
+      # expression shapes that JSX components in real codebases use most
+      # often: bare identifiers, literals, simple member-expression chains
+      # (`item.label`), and template literals composed of identifier
+      # interpolations. Anything more complex (function calls, conditionals,
+      # subscripts) returns `nil` from `#translate` so the backend can emit
+      # a TODO marker and fall back to the verbatim JS source.
+      #
+      # Identifier resolution:
+      #   * Names in the active local scope (e.g. loop bindings) translate
+      #     to the bare snake_case identifier.
+      #   * Names in `prop_names` translate to a `@snake_case` instance
+      #     variable.
+      #   * Anything else translates to the bare snake_case identifier and
+      #     is recorded as unresolved.
+      #
+      # Local scopes can be pushed via `with_locals` and stack — each
+      # entry shadows lower entries.
+      class ExpressionTranslator
+        IDENTIFIER = /\A[a-zA-Z_$][a-zA-Z_$0-9]*\z/
+        STRING_LITERAL = /\A(['"])(.*)\1\z/m
+        NUMBER_LITERAL = /\A-?\d+(\.\d+)?\z/
+        TEMPLATE_LITERAL = /\A`(.*)`\z/m
+        TEMPLATE_INTERPOLATION = /\$\{([a-zA-Z_$][a-zA-Z_$0-9]*(?:\.[a-zA-Z_$][a-zA-Z_$0-9]*)*)\}/
+        MEMBER_CHAIN = /\A(?<root>[a-zA-Z_$][a-zA-Z_$0-9]*)(?<rest>(?:\.[a-zA-Z_$][a-zA-Z_$0-9]*)+)\z/
+        UNARY = /\A(?<op>!+|-|\+)(?<operand>.+)\z/m
+        SIMPLE_LITERALS = { "null" => "nil", "undefined" => "nil", "true" => "true", "false" => "false" }.freeze
+
+        Result = Data.define(:ruby, :unresolved_identifiers)
+
+        def initialize(prop_names:)
+          @prop_names = prop_names.to_set
+          @local_stack = []
+        end
+
+        def with_locals(names)
+          @local_stack.push(names.compact)
+          yield
+        ensure
+          @local_stack.pop
+        end
+
+        def translate(source)
+          source = source.strip
+          unresolved = []
+
+          ruby = translate_ruby(source, unresolved)
+          ruby && Result.new(ruby: ruby, unresolved_identifiers: unresolved.uniq)
+        end
+
+        private
+
+        def translate_ruby(source, unresolved)
+          if SIMPLE_LITERALS.key?(source) then SIMPLE_LITERALS[source]
+          elsif source.match?(NUMBER_LITERAL) || source.match?(STRING_LITERAL) then source
+          elsif source.match?(IDENTIFIER) then translate_identifier(source, unresolved)
+          elsif (m = MEMBER_CHAIN.match(source)) then translate_member_chain(m[:root], m[:rest], unresolved)
+          elsif (m = TEMPLATE_LITERAL.match(source)) then translate_template_literal(m[1], unresolved)
+          elsif (m = UNARY.match(source))
+            translate_unary(m[:op], m[:operand], unresolved)
+          end
+        end
+
+        def translate_unary(operator, operand, unresolved)
+          inner = translate_ruby(operand.strip, unresolved)
+          inner && "#{operator}#{inner}"
+        end
+
+        def in_local_scope?(name)
+          @local_stack.any? { |scope| scope.include?(name) }
+        end
+
+        def translate_identifier(name, unresolved)
+          snake = AST::Inflector.underscore(name)
+          if in_local_scope?(name)
+            snake
+          elsif @prop_names.include?(name)
+            "@#{snake}"
+          else
+            unresolved << name
+            snake
+          end
+        end
+
+        def translate_member_chain(root, rest, unresolved)
+          translated_root = translate_identifier(root, unresolved)
+          # Underscore each chain segment so JS camelCase identifiers map to
+          # Ruby snake_case (`post.coverImage` → `post.cover_image`).
+          ruby_rest = rest.gsub(/\.([a-zA-Z_$][a-zA-Z_$0-9]*)/) do
+            ".#{AST::Inflector.underscore(::Regexp.last_match(1))}"
+          end
+          "#{translated_root}#{ruby_rest}"
+        end
+
+        def translate_template_literal(content, unresolved)
+          return nil if content.include?("\\`")
+          return nil if content.scan("${").size != content.scan(TEMPLATE_INTERPOLATION).size
+
+          ruby_content = content.gsub(TEMPLATE_INTERPOLATION) do |_match|
+            captured = ::Regexp.last_match(1)
+            translated = if (m = MEMBER_CHAIN.match(captured))
+                           translate_member_chain(m[:root], m[:rest], unresolved)
+                         else
+                           translate_identifier(captured, unresolved)
+                         end
+            "\#{#{translated}}"
+          end
+          %("#{ruby_content}")
+        end
+      end
+    end
+  end
+end