jsx_rosetta 0.4.0 → 0.6.0

data/lib/jsx_rosetta/backend/view_component.rb

@@ -42,6 +42,32 @@ module JsxRosetta
         "Image" => { method: :image_tag, positional: :src }.freeze
       }.freeze
 
+      # Per-library TODO header lines surfaced above the verbatim hook
+      # source. Each library has a different Rails analog, so we don't
+      # collapse them into a single generic block. Keys must mirror the
+      # `:library` values produced by IR::Lowering. First line is rendered
+      # with the `<%#` opener; subsequent lines are indented continuation.
+      HOOK_TODO_HEADERS = {
+        react: [
+          "TODO: React hooks detected. None translate automatically. Hotwire/Stimulus",
+          "handles behavior; controllers/views handle state; turbo-frames handle async",
+          "loading. Original source:"
+        ].freeze,
+        apollo: [
+          "TODO: Apollo data-fetching hooks detected. None translate automatically.",
+          "Move the fetch to the Rails controller (or a model/service); pass the",
+          "result in as a prop. For useMutation, use a form POST + redirect or a",
+          "Turbo Stream response. Original source:"
+        ].freeze,
+        next_js: [
+          "TODO: Next.js navigation hooks detected. None translate automatically.",
+          "Rails analogs: useRouter -> redirect_to / form actions;",
+          "usePathname -> request.path; useSearchParams / useParams -> params;",
+          "useSelectedLayoutSegment(s) -> match against request.path in the view.",
+          "Original source:"
+        ].freeze
+      }.freeze
+
       def initialize(helpers: nil, layout: :sidecar)
         super()
         @helpers = case helpers
@@ -56,16 +82,18 @@ module JsxRosetta
         @layout = layout
       end
 
-      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, local_binding_names: component.local_binding_names
-        )
-
+      def emit(component, source_filename: nil) # rubocop:disable Lint/UnusedMethodArgument
+        translator = build_translator(component)
         base_name = "#{AST::Inflector.underscore(component.name)}_component"
         @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
 
+        # Data-factory components (column-descriptor modules) have no
+        # template — they're pure-data classes. Skip the .erb pair and
+        # emit a single .rb with the factory method. JSX render lambdas
+        # inside the data have nowhere to live in the ViewComponent
+        # ERB-template world, so we surface a TODO note in the class.
+        return emit_data_factory(component) if component.mode == :data_factory
+
         files = [
           File.new(path: "#{base_name}.rb", contents: render_ruby_class(component, translator)),
           File.new(path: erb_path(base_name), contents: render_erb_template(component, translator))
@@ -79,6 +107,85 @@ module JsxRosetta
         files
       end
 
+      # For data-factory components emit a plain Ruby class (no ApplicationViewComponent
+      # base, no ERB template). The user can mix it into a ViewComponent or call
+      # the method directly — the goal is to surface the translated data array,
+      # not to render it in isolation.
+      def emit_data_factory(component)
+        method_name = AST::Inflector.underscore(component.name)
+        param_names = component.props.map(&:name)
+        translator = ExpressionTranslator.new(prop_names: [], local_binding_names: param_names)
+        signature = data_factory_signature(method_name, param_names)
+        body = translator.with_locals(param_names) do
+          inline_render_value(component.body, translator, indent: 4)
+        end
+        contents = <<~RUBY
+          # frozen_string_literal: true
+
+          # TODO: data-factory module — the translated array contains JSX render
+          # lambdas as `nil` placeholders. Wire each up to a Phlex helper or a
+          # method on the consuming ViewComponent.
+          class #{class_name_for(component)}
+            def #{signature}
+              #{body}
+            end
+          end
+        RUBY
+        [File.new(path: "#{AST::Inflector.underscore(component.name)}.rb", contents: contents)]
+      end
+
+      def class_name_for(component)
+        component.name[0].upcase + component.name[1..]
+      end
+
+      def data_factory_signature(method_name, param_names)
+        return method_name if param_names.empty?
+
+        kwargs = param_names.map { |name| "#{AST::Inflector.underscore(name)}: nil" }
+        "#{method_name}(#{kwargs.join(", ")})"
+      end
+
+      # Recursively render a non-JSX value (ObjectLiteral / ArrayLiteral /
+      # Lambda / Interpolation / primitives) without the kwarg-list
+      # context the Phlex backend uses. IR::Lambda and unmatched cases
+      # both fall through to `nil` — there's no Phlex class to host a
+      # rendered method body, and the class-level TODO comment above the
+      # emitted file already flags both for the reviewer.
+      def inline_render_value(value, translator, indent: 0)
+        case value
+        when IR::ObjectLiteral then render_factory_object_literal(value, translator, indent: indent)
+        when IR::ArrayLiteral then render_factory_array_literal(value, translator, indent: indent)
+        when IR::Interpolation then translator.translate(value.expression)&.ruby || "nil"
+        when String then value.inspect
+        when true then "true"
+        else "nil"
+        end
+      end
+
+      def render_factory_object_literal(obj, translator, indent:)
+        parts = obj.properties.map do |(key, value)|
+          rendered = inline_render_value(value, translator, indent: indent + 2)
+          snake = AST::Inflector.underscore(key)
+          if snake.match?(/\A[a-z_][a-z0-9_]*\z/)
+            "#{snake}: #{rendered}"
+          else
+            "#{key.inspect} => #{rendered}"
+          end
+        end
+        "{ #{parts.join(", ")} }"
+      end
+
+      def render_factory_array_literal(arr, translator, indent:)
+        parts = arr.elements.map do |el|
+          el.nil? ? "nil" : inline_render_value(el, translator, indent: indent + 2)
+        end
+        return "[]" if parts.empty?
+
+        pad = " " * (indent + 2)
+        close_pad = " " * indent
+        "[\n#{pad}#{parts.join(",\n#{pad}")}\n#{close_pad}]"
+      end
+
       def erb_path(base_name)
         @layout == :sidecar ? "#{base_name}/#{base_name}.html.erb" : "#{base_name}.html.erb"
       end
@@ -123,6 +230,20 @@ module JsxRosetta
 
       private
 
+      def build_translator(component)
+        prop_names = component.props.map(&:name)
+        prop_names << component.rest_prop_name if component.rest_prop_name
+        prop_aliases = component.props.each_with_object({}) do |prop, hash|
+          hash[prop.alias_name] = prop.name if prop.alias_name
+        end
+        ExpressionTranslator.new(
+          prop_names: prop_names,
+          local_binding_names: component.local_binding_names,
+          prop_aliases: prop_aliases,
+          imported_names: component.module_imports.map(&:name) + component.module_bindings.map(&:name)
+        )
+      end
+
       def initializable_props(component)
         component.props.reject { |prop| prop.name == DEFAULT_SLOT_NAME }
       end
@@ -131,21 +252,50 @@ module JsxRosetta
         props = initializable_props(component)
         rest_name = component.rest_prop_name
 
-        body = if props.empty? && rest_name.nil?
-                 <<~RUBY
-                   # frozen_string_literal: true
-
-                   class #{component.name}Component < ::ViewComponent::Base
-                   end
-                 RUBY
-               else
-                 render_ruby_class_with_props(component, props, rest_name, translator)
-               end
+        body = render_class_with_optional_props(component, props, rest_name, translator)
+        body = inject_render_method_skeletons(body, component)
 
         prefix = render_module_bindings_prefix(component)
         prefix.empty? ? body : insert_module_bindings_prefix(body, prefix)
       end
 
+      def render_class_with_optional_props(component, props, rest_name, translator)
+        if props.empty? && rest_name.nil?
+          <<~RUBY
+            # frozen_string_literal: true
+
+            class #{component.name}Component < ::ViewComponent::Base
+            end
+          RUBY
+        else
+          render_ruby_class_with_props(component, props, rest_name, translator)
+        end
+      end
+
+      # For each RenderMethod, emit a method skeleton on the class just
+      # before the closing `end`. ERB-rendered VC bodies don't translate
+      # cleanly to Ruby methods (Phlex does — see its renderer), so the
+      # skeleton stays empty and the JSX source is preserved as a comment
+      # for the reviewer to translate by hand.
+      def inject_render_method_skeletons(body, component)
+        return body if component.render_methods.empty?
+
+        skeletons = component.render_methods.map { |rm| render_method_skeleton(rm) }
+        body.sub(/(\n)end\n\z/, "\n\n#{skeletons.join("\n\n")}\\1end\n")
+      end
+
+      def render_method_skeleton(render_method)
+        snake_params = render_method.params.map { |p| AST::Inflector.underscore(p) }
+        signature = snake_params.empty? ? render_method.name : "#{render_method.name}(#{snake_params.join(", ")})"
+        [
+          "  # TODO: translate the JSX body for #{render_method.name} — was a",
+          "  # local arrow returning JSX in the source component.",
+          "  def #{signature}",
+          "    \"\"",
+          "  end"
+        ].join("\n")
+      end
+
       def render_module_bindings_prefix(component)
         return "" if component.module_bindings.empty?
 
@@ -169,14 +319,15 @@ module JsxRosetta
       end
 
       def render_ruby_class_with_props(component, props, rest_name, translator)
+        rest_snake = rest_name && AST::Inflector.underscore(rest_name)
         kwargs = props.map { |prop| ruby_kwarg(prop, translator) }
-        kwargs << "**#{rest_name}" if rest_name
+        kwargs << "**#{rest_snake}" if rest_snake
 
         assignments = props.map do |prop|
           snake = AST::Inflector.underscore(prop.name)
           "    @#{snake} = #{snake}"
         end
-        assignments << "    @#{rest_name} = #{rest_name}" if rest_name
+        assignments << "    @#{rest_snake} = #{rest_snake}" if rest_snake
 
         <<~RUBY
           # frozen_string_literal: true
@@ -265,14 +416,20 @@ module JsxRosetta
       def render_react_hooks_todo(hooks)
         return "" if hooks.empty?
 
-        lines = [
-          "<%# TODO: React hooks detected. None translate automatically. Hotwire/Stimulus",
-          "    handles behavior; controllers/views handle state; turbo-frames handle async",
-          "    loading. Original source:"
-        ]
-        hooks.each { |hook| lines << "    #{hook.source}" }
+        blocks = hooks.group_by(&:library).map { |library, calls| hook_todo_block(library, calls) }
+        "#{blocks.join("\n")}\n"
+      end
+
+      def hook_todo_block(library, calls)
+        header_lines = HOOK_TODO_HEADERS.fetch(library, HOOK_TODO_HEADERS[:react])
+        lines = ["<%# #{header_lines.first}"]
+        header_lines.drop(1).each { |line| lines << "    #{line}" }
+        calls.each do |call|
+          lines << "    operation: #{call.operation}" if call.operation
+          lines << "    #{call.source}"
+        end
         lines << "%>"
-        "#{lines.join("\n")}\n"
+        lines.join("\n")
       end
 
       def render_ir_node(node, translator, indent:)
@@ -283,6 +440,7 @@ module JsxRosetta
         when IR::Conditional then render_conditional(node, translator, indent: indent)
         when IR::Loop then render_loop(node, translator, indent: indent)
         when IR::RenderProp then render_orphan_render_prop(node, translator, indent: indent)
+        when IR::LocalRenderCall then render_local_render_call(node, translator, indent: indent)
         when IR::Slot then render_slot(node, indent: indent)
         when IR::Text then "#{spaces(indent)}#{node.value}"
         when IR::Interpolation then "#{spaces(indent)}#{interpolation_to_erb(node, translator)}"
@@ -290,6 +448,23 @@ module JsxRosetta
         end
       end
 
+      # `{renderHeader(arg)}` → `<%= render_header(arg) %>`. The matching
+      # method definition is emitted on the component class via
+      # `render_render_methods_section`. The class method returns an
+      # HTML-safe string (Rails' `content_tag` / `safe_join` is the
+      # canonical approach), and `<%= %>` interpolates it into the template.
+      def render_local_render_call(call, translator, indent:)
+        if call.args.empty?
+          "#{spaces(indent)}<%= #{call.method_name} %>"
+        else
+          arg_sources = call.args.map do |arg|
+            translated = translator.translate(arg.expression)
+            translated ? translated.ruby : arg.expression
+          end
+          "#{spaces(indent)}<%= #{call.method_name}(#{arg_sources.join(", ")}) %>"
+        end
+      end
+
       def render_orphan_render_prop(render_prop, translator, indent:)
         translator.with_locals(render_prop.params) do
           render_ir_node(render_prop.body, translator, indent: indent)
@@ -531,9 +706,16 @@ module JsxRosetta
         lines.join("\n")
       end
 
+      # A translated value of `"nil"` is treated as untranslatable: the
+      # translator emits `"nil"` for known-local bindings (so the file
+      # loads as a leaf reference), but driving an `<% if %>` with `nil`
+      # silently disables the whole branch. Fall back to the verbatim
+      # expression so the human reviewer sees what needs translating.
       def render_test_expression(test, translator)
         translated = translator.translate(test.expression)
-        translated ? translated.ruby : test.expression
+        return translated.ruby if translated && translated.ruby != "nil"
+
+        test.expression
       end
 
       def render_slot(slot, indent:)
@@ -644,7 +826,7 @@ module JsxRosetta
       # literal portions literally and the interpolations as ERB tags.
       def plain_attribute_value_erb(interpolation, translator)
         translated = translator.translate(interpolation.expression)
-        if double_quoted_ruby_string?(translated&.ruby) && translated.unresolved_identifiers.empty?
+        if quoted_ruby_string?(translated&.ruby) && translated.unresolved_identifiers.empty?
           inlined_ruby_string(translated.ruby)
         else
           interpolation_to_erb(interpolation, translator)
@@ -653,7 +835,7 @@ module JsxRosetta
 
       def render_style_binding(binding, translator)
         translated = translator.translate(binding.expression)
-        if double_quoted_ruby_string?(translated&.ruby)
+        if quoted_ruby_string?(translated&.ruby)
           %(class="#{inlined_ruby_string(translated.ruby)}")
         elsif translated
           %(class="<%= #{translated.ruby} %>")
@@ -662,8 +844,11 @@ module JsxRosetta
         end
       end
 
-      def double_quoted_ruby_string?(ruby)
-        ruby.is_a?(String) && ruby.start_with?('"') && ruby.end_with?('"')
+      def quoted_ruby_string?(ruby)
+        ruby.is_a?(String) && (
+          (ruby.start_with?('"') && ruby.end_with?('"')) ||
+          (ruby.start_with?("'") && ruby.end_with?("'"))
+        )
       end
 
       # Given a Ruby double-quoted string with #{...} interpolations, emit it
@@ -727,6 +912,51 @@ module JsxRosetta
         when IR::Interpolation
           translated = translator.translate(value.expression)
           translated ? translated.ruby : "nil # TODO: translate #{value.expression.inspect}"
+        when IR::ComponentInvocation
+          component_invocation_inline_value(value, translator)
+        when IR::Element, IR::Fragment
+          "nil # TODO: couldn't inline JSX value: #{jsx_value_summary(value)}"
+        end
+      end
+
+      # JSX appearing as an attribute value — `icon={<Foo/>}` etc. — lowered
+      # in v0.5.x. Emit a component-instance value (`icon: FooComponent.new`)
+      # so the receiving ViewComponent can `render @icon`. With children we
+      # use Ruby block syntax (`FooComponent.new { ... }`) when the body
+      # fits one line; otherwise we drop with a TODO so the kwarg stays
+      # valid Ruby. Cases requiring a Phlex execution context (IR::Element,
+      # multi-element IR::Fragment) drop with a TODO too — out of MVP scope.
+      def component_invocation_inline_value(invocation, translator)
+        return inline_render_prop_todo if invocation.children.any?(IR::RenderProp)
+
+        kwargs = component_invocation_kwargs(invocation.props, translator)
+        class_name = component_class_name(invocation.name)
+        new_call = kwargs.empty? ? "#{class_name}.new" : "#{class_name}.new(#{kwargs})"
+        return new_call if invocation.children.empty?
+
+        block_body = inline_children_body(invocation.children, translator)
+        return "nil # TODO: couldn't inline JSX value: <#{invocation.name}...>" unless block_body
+
+        "#{new_call} { #{block_body} }"
+      end
+
+      def inline_render_prop_todo
+        "nil # TODO: couldn't inline render-prop value"
+      end
+
+      def inline_children_body(children, translator)
+        rendered = children.map { |c| render_ir_node(c, translator, indent: 0).strip }
+        return nil if rendered.any? { |line| line.include?("\n") }
+
+        joined = rendered.join("; ")
+        joined.empty? || joined.length > 100 ? nil : joined
+      end
+
+      def jsx_value_summary(value)
+        case value
+        when IR::Element then "<#{value.tag}...>"
+        when IR::Fragment then "<>...</>"
+        else "<JSX>"
         end
       end
 

data/lib/jsx_rosetta/cli.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "json"
 require "open3"
+require "pathname"
 
 require_relative "node_bridge"
 
@@ -15,6 +16,8 @@ module JsxRosetta
   #                              (default: current directory). TSX is detected
   #                              via the .tsx extension or --tsx.
   #   parse FILE                 Print the parsed Babel AST as pretty JSON.
+  #   pages-routes DIR [-o PATH] Walk a Next.js `pages/` directory and emit a
+  #                              Rails config/routes.rb skeleton.
   #   version                    Print the gem version.
   #   help                       Show usage.
   class CLI
@@ -22,6 +25,43 @@ module JsxRosetta
     EXIT_USAGE = 64
     EXIT_FAILURE = 1
 
+    USAGE_TEXT = <<~USAGE
+      Usage: jsx_rosetta <command> [args]
+
+      Commands:
+        install                    Install the gem's Node sidecar dependencies (runs `npm install`).
+        translate FILE [-o DIR]    Translate JSX/TSX into ViewComponent files in DIR (default: ".").
+                                   Pass --tsx to force TypeScript parsing if the input is .jsx.
+                                   Pass --as=view to emit a Rails view template (`<snake>.html.erb`)
+                                   instead of a ViewComponent class + sidecar template — appropriate
+                                   for pages tied to a route.
+                                   Pass --as=phlex to emit a single-file Phlex 2.x view class
+                                   (`<snake>.rb`) instead of a ViewComponent. Configure the class
+                                   name with --phlex-suffix=Component or --phlex-namespace=Components
+                                   (mutually exclusive; default is bare class name).
+                                   Pass --rails-routes DIR (with --as=phlex) to place the output
+                                   at <controller>/<action>.rb with class
+                                   Views::<Controller>::<Action> < Views::Base, derived from a
+                                   route table scanned out of DIR (a Next.js pages directory).
+        routes FILE [-o OUT.rb]    Parse <Route path=... element={<X/>} /> patterns from FILE
+                                   and emit a reviewable Ruby script that calls `rails generate
+                                   controller` and prints suggested config/routes.rb additions.
+        pages-routes DIR [-o PATH] Walk a Next.js `pages/` directory tree and emit a
+                                   Rails config/routes.rb skeleton derived from the file
+                                   layout. Use --ext .tsx,.jsx,.ts,.js to override the
+                                   default `.tsx,.jsx` filter, and --allow-any-dir to
+                                   skip the `basename == 'pages'` safety check.
+                                   Pass --controllers DIR to also emit one
+                                   `<controller>_controller.rb` per controller in DIR
+                                   (existing files are not overwritten).
+        parse FILE                 Parse the input and print the Babel AST as JSON.
+        version                    Print the gem version.
+        help                       Show this help.
+
+      Environment:
+        JSX_ROSETTA_NODE           Absolute path to a node executable (default: PATH lookup).
+    USAGE
+
     def initialize(argv = ARGV.dup, stdout: $stdout, stderr: $stderr)
       @argv = argv
       @stdout = stdout
@@ -34,6 +74,7 @@ module JsxRosetta
       when "install" then run_install
       when "translate" then run_translate
       when "routes" then run_routes
+      when "pages-routes" then run_pages_routes
       when "parse" then run_parse
       when "version", "-v", "--version" then run_version
       when nil, "help", "-h", "--help" then print_help(EXIT_OK)
@@ -61,6 +102,8 @@ module JsxRosetta
       input_path = positional.first
       return missing_argument("translate FILE", "translate") unless input_path
 
+      resolve_rails_view_route!(options, input_path)
+
       out_dir = options[:out] || "."
       typescript = options[:tsx] || input_path.end_with?(".tsx")
       backend = backend_for_as(options[:as])
@@ -72,7 +115,8 @@ module JsxRosetta
         backend: backend,
         backend_options: backend_options,
         typescript: typescript,
-        source_filename: input_path
+        source_filename: input_path,
+        keep_slot: options[:keep_slot] || false
       )
 
       write_emitted_files(files, out_dir)
@@ -93,7 +137,40 @@ module JsxRosetta
     def backend_options_for(backend, options)
       return {} unless backend == :phlex
 
-      { suffix: options[:phlex_suffix], namespace: options[:phlex_namespace] }.compact
+      base = { suffix: options[:phlex_suffix], namespace: options[:phlex_namespace] }.compact
+      base[:rails_view] = options[:rails_view_route] if options[:rails_view_route]
+      base[:route_table] = options[:route_table] if options[:route_table]
+      base
+    end
+
+    def resolve_rails_view_route!(options, input_path)
+      pages_dir = options[:rails_routes]
+      return unless pages_dir
+
+      raise ArgumentError, "--rails-routes requires --as=phlex" unless options[:as] == "phlex"
+      if options[:phlex_suffix] || options[:phlex_namespace]
+        raise ArgumentError, "--rails-routes cannot be combined with --phlex-suffix or --phlex-namespace"
+      end
+
+      ensure_pages_dir!(pages_dir, allow_any: options[:allow_any_dir])
+      rel = relative_path_under(input_path, pages_dir)
+      raise ArgumentError, "#{input_path} is not under #{pages_dir}" unless rel
+
+      routes, _skipped = PagesRouting.scan(pages_dir, extensions: options[:ext] || PagesRouting::DEFAULT_EXTENSIONS)
+      route = routes.find { |r| r.source_path == rel }
+      raise ArgumentError, "#{rel} has no route in #{pages_dir} (skipped or non-page file?)" unless route
+
+      options[:rails_view_route] = route
+      options[:route_table] = routes
+    end
+
+    def relative_path_under(file_path, dir)
+      file = Pathname.new(File.expand_path(file_path))
+      base = Pathname.new(File.expand_path(dir))
+      rel = file.relative_path_from(base).to_s
+      rel unless rel.start_with?("..")
+    rescue ArgumentError
+      nil
     end
 
     def write_emitted_files(files, out_dir)
@@ -129,6 +206,53 @@ module JsxRosetta
       EXIT_FAILURE
     end
 
+    def run_pages_routes
+      options, positional = parse_translate_options
+      input_dir = positional.first
+      return missing_argument("pages-routes DIR [-o OUT.rb]", "pages-routes") unless input_dir
+
+      ensure_pages_dir!(input_dir, allow_any: options[:allow_any_dir])
+      extensions = options[:ext] || PagesRouting::DEFAULT_EXTENSIONS
+      routes, skipped = PagesRouting.scan(input_dir, extensions: extensions)
+      contents = PagesRouting.emit(routes: routes, skipped: skipped, source_dir: input_dir)
+
+      if options[:out]
+        File.write(options[:out], contents)
+        @stdout.puts "wrote #{options[:out]}"
+      else
+        @stdout.print(contents)
+      end
+
+      write_controllers(routes, options[:controllers]) if options[:controllers]
+      EXIT_OK
+    rescue ArgumentError => e
+      @stderr.puts "jsx_rosetta pages-routes: #{e.message}"
+      EXIT_FAILURE
+    end
+
+    def write_controllers(routes, dir)
+      FileUtils.mkdir_p(dir)
+      PagesRouting.emit_controllers(routes: routes).each do |file|
+        target = File.join(dir, file.path)
+        if File.exist?(target)
+          @stdout.puts "skipped #{target} (exists)"
+        else
+          File.write(target, file.contents)
+          @stdout.puts "wrote #{target}"
+        end
+      end
+    end
+
+    def ensure_pages_dir!(dir, allow_any:)
+      return if allow_any
+      return if File.basename(dir) == "pages"
+      return if File.directory?(File.join(dir, "pages"))
+
+      raise ArgumentError,
+            "#{dir.inspect} does not look like a Next.js pages directory " \
+            "(basename != 'pages' and no nested 'pages/'). Pass --allow-any-dir to override."
+    end
+
     def run_parse
       options, positional = parse_translate_options
       input_path = positional.first
@@ -157,22 +281,59 @@ module JsxRosetta
 
       until @argv.empty?
         arg = @argv.shift
-        case arg
-        when "-o", "--out" then options[:out] = @argv.shift
-        when "--tsx", "--typescript" then options[:tsx] = true
-        when "--as" then options[:as] = @argv.shift
-        when /\A--as=(.+)\z/ then options[:as] = ::Regexp.last_match(1)
-        when "--phlex-suffix" then options[:phlex_suffix] = @argv.shift
-        when /\A--phlex-suffix=(.*)\z/ then options[:phlex_suffix] = ::Regexp.last_match(1)
-        when "--phlex-namespace" then options[:phlex_namespace] = @argv.shift
-        when /\A--phlex-namespace=(.+)\z/ then options[:phlex_namespace] = ::Regexp.last_match(1)
-        else positional << arg
-        end
+        positional << arg unless option_consumed?(arg, options)
       end
 
       [options, positional]
     end
 
+    def option_consumed?(arg, options)
+      consume_translate_option?(arg, options) ||
+        consume_phlex_option?(arg, options) ||
+        consume_pages_routes_option?(arg, options)
+    end
+
+    def consume_translate_option?(arg, options)
+      case arg
+      when "-o", "--out" then options[:out] = @argv.shift
+      when "--tsx", "--typescript" then options[:tsx] = true
+      when "--as" then options[:as] = @argv.shift
+      when /\A--as=(.+)\z/ then options[:as] = ::Regexp.last_match(1)
+      when "--keep-slot" then options[:keep_slot] = true
+      else return false
+      end
+      true
+    end
+
+    def consume_phlex_option?(arg, options)
+      case arg
+      when "--phlex-suffix" then options[:phlex_suffix] = @argv.shift
+      when /\A--phlex-suffix=(.*)\z/ then options[:phlex_suffix] = ::Regexp.last_match(1)
+      when "--phlex-namespace" then options[:phlex_namespace] = @argv.shift
+      when /\A--phlex-namespace=(.+)\z/ then options[:phlex_namespace] = ::Regexp.last_match(1)
+      when "--rails-routes" then options[:rails_routes] = @argv.shift
+      when /\A--rails-routes=(.+)\z/ then options[:rails_routes] = ::Regexp.last_match(1)
+      else return false
+      end
+      true
+    end
+
+    def consume_pages_routes_option?(arg, options)
+      case arg
+      when "--ext" then options[:ext] = parse_ext_list(@argv.shift)
+      when /\A--ext=(.+)\z/ then options[:ext] = parse_ext_list(::Regexp.last_match(1))
+      when "--allow-any-dir" then options[:allow_any_dir] = true
+      when "--controllers" then options[:controllers] = @argv.shift
+      when /\A--controllers=(.+)\z/ then options[:controllers] = ::Regexp.last_match(1)
+      else return false
+      end
+      true
+    end
+
+    def parse_ext_list(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?).map { |ext| ext.start_with?(".") ? ext : ".#{ext}" }
+    end
+
     def missing_argument(usage, command)
       @stderr.puts "jsx_rosetta #{command}: missing required argument."
       @stderr.puts "  usage: jsx_rosetta #{usage}"
@@ -180,30 +341,7 @@ module JsxRosetta
     end
 
     def print_help(exit_code)
-      @stdout.puts <<~USAGE
-        Usage: jsx_rosetta <command> [args]
-
-        Commands:
-          install                    Install the gem's Node sidecar dependencies (runs `npm install`).
-          translate FILE [-o DIR]    Translate JSX/TSX into ViewComponent files in DIR (default: ".").
-                                     Pass --tsx to force TypeScript parsing if the input is .jsx.
-                                     Pass --as=view to emit a Rails view template (`<snake>.html.erb`)
-                                     instead of a ViewComponent class + sidecar template — appropriate
-                                     for pages tied to a route.
-                                     Pass --as=phlex to emit a single-file Phlex 2.x view class
-                                     (`<snake>.rb`) instead of a ViewComponent. Configure the class
-                                     name with --phlex-suffix=Component or --phlex-namespace=Components
-                                     (mutually exclusive; default is bare class name).
-          routes FILE [-o OUT.rb]    Parse <Route path=... element={<X/>} /> patterns from FILE
-                                     and emit a reviewable Ruby script that calls `rails generate
-                                     controller` and prints suggested config/routes.rb additions.
-          parse FILE                 Parse the input and print the Babel AST as JSON.
-          version                    Print the gem version.
-          help                       Show this help.
-
-        Environment:
-          JSX_ROSETTA_NODE           Absolute path to a node executable (default: PATH lookup).
-      USAGE
+      @stdout.puts USAGE_TEXT
       exit_code
     end
   end