jsx_rosetta 0.3.0 → 0.5.1

data/lib/jsx_rosetta/ir/module_shape_classifier.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "../ast/node"
+
+module JsxRosetta
+  module IR
+    # Heuristic classifier that labels a module whose top-level shape
+    # isn't a function component. Used by Lowering::no_component_error
+    # to produce triage-friendly messages explaining *why* a file didn't
+    # translate. Pure function: program in, label symbol out — no
+    # mutable state, no relationship to the rest of the lowering
+    # pipeline.
+    #
+    # Labels (in priority order — more specific shapes win):
+    #   :class_component    `class X extends React.Component { ... }`
+    #   :hoc_wrapped        `const X = React.memo(...)` etc.
+    #   :columns_data       top-level array literal export
+    #   :hooks_only         every export is a `use*` hook
+    #   :utils_only         every export is a lowercase non-hook helper
+    #   :mixed_exports      mixes hooks + non-hook lowercase exports
+    #   :side_effects_only  top-level expression statements, no exports
+    #   :types_only         types/constants only, no functions
+    #   :unknown            no signal — caller emits the bare error
+    class ModuleShapeClassifier
+      EXPORT_TYPES = %w[ExportNamedDeclaration ExportDefaultDeclaration].freeze
+      HOC_NAMES = %w[memo forwardRef lazy observer].freeze
+
+      def self.classify(program)
+        new(program).classify
+      end
+
+      def initialize(program)
+        @program = program
+      end
+
+      def classify
+        ast_shape = classify_ast_shape
+        return ast_shape if ast_shape
+
+        classify_by_export_names(top_level_export_names)
+      end
+
+      private
+
+      def classify_ast_shape
+        return :class_component if @program.body.any? { |stmt| class_component?(stmt) }
+        return :hoc_wrapped if @program.body.any? { |stmt| hoc_wrapped_export?(stmt) }
+        return :columns_data if @program.body.any? { |stmt| array_literal_export?(stmt) }
+
+        nil
+      end
+
+      def classify_by_export_names(names)
+        export_label = classify_by_export_pattern(names)
+        return export_label if export_label
+
+        classify_non_export_module
+      end
+
+      def classify_by_export_pattern(names)
+        any_hooks = names.any? { |n| hook_name?(n) }
+        any_helpers = names.any? { |n| /\A[a-z]/.match?(n) && !hook_name?(n) }
+        return :mixed_exports if any_hooks && any_helpers
+        return :hooks_only if any_hooks
+        return :utils_only if any_helpers
+
+        nil
+      end
+
+      def classify_non_export_module
+        return :side_effects_only if @program.body.any? { |s| side_effect_statement?(s) }
+        return :types_only if top_level_has_anything?
+
+        :unknown
+      end
+
+      def hook_name?(name)
+        name.start_with?("use") && name.length > 3 && name[3] == name[3].upcase
+      end
+
+      # Only flag class-component shape when the class has no usable render
+      # method. Classes WITH `render()` lower via the
+      # ClassDeclaration → ViewComponent path added in v0.5.0, so the
+      # classifier should leave them alone and let the regular component
+      # finder pick them up.
+      def class_component?(stmt)
+        decl = stmt.of_type?(*EXPORT_TYPES) ? stmt[:declaration] : stmt
+        return false unless AST::Node.matches?(decl, "ClassDeclaration")
+
+        !class_has_render_method?(decl)
+      end
+
+      def class_has_render_method?(class_decl)
+        body = class_decl.child(:body)
+        return false unless body
+
+        body[:body].any? do |member|
+          next false unless AST::Node.matches?(member, "ClassMethod", "MethodDefinition")
+
+          key = member.child(:key)
+          AST::Node.matches?(key, "Identifier") && key[:name] == "render" && member[:kind] != "constructor"
+        end
+      end
+
+      # Recognize `export const X = React.memo(...)` (export wrapper) or a
+      # top-level `const X = lazy(() => ...)` followed by `export default X`
+      # — a VariableDeclaration whose init is a CallExpression to a known HOC.
+      def hoc_wrapped_export?(stmt)
+        decl = stmt.of_type?(*EXPORT_TYPES) ? stmt[:declaration] : stmt
+        return false unless AST::Node.matches?(decl, "VariableDeclaration")
+
+        decl[:declarations].any? do |d|
+          init = d[:init]
+          AST::Node.matches?(init, "CallExpression") && hoc_callee?(init[:callee])
+        end
+      end
+
+      def hoc_callee?(callee)
+        return false unless callee.is_a?(AST::Node)
+
+        case callee.type
+        when "Identifier" then HOC_NAMES.include?(callee[:name])
+        when "MemberExpression"
+          property = callee.child(:property)
+          property&.of_type?("Identifier") && HOC_NAMES.include?(property[:name])
+        else false
+        end
+      end
+
+      def array_literal_export?(stmt)
+        return false unless stmt.of_type?(*EXPORT_TYPES)
+
+        decl = stmt[:declaration]
+        return true if AST::Node.matches?(decl, "ArrayExpression")
+        return false unless AST::Node.matches?(decl, "VariableDeclaration")
+
+        decl[:declarations].any? { |d| AST::Node.matches?(d[:init], "ArrayExpression") }
+      end
+
+      def side_effect_statement?(stmt)
+        AST::Node.matches?(stmt, "ExpressionStatement")
+      end
+
+      def top_level_has_anything?
+        @program.body.any? { |stmt| stmt.is_a?(AST::Node) && !stmt.of_type?("ImportDeclaration") }
+      end
+
+      def top_level_export_names
+        @program.body.flat_map { |stmt| extract_top_level_names(stmt) }.compact
+      end
+
+      def extract_top_level_names(stmt)
+        case stmt.type
+        when "FunctionDeclaration"
+          [stmt.child(:id)&.[](:name)]
+        when "VariableDeclaration"
+          stmt[:declarations].map { |d| AST::Node.matches?(d[:id], "Identifier") ? d[:id][:name] : nil }
+        when "ExportNamedDeclaration", "ExportDefaultDeclaration"
+          decl = stmt.child(:declaration)
+          decl ? extract_top_level_names(decl) : []
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/ir/types.rb

@@ -20,18 +20,58 @@ module JsxRosetta
     #                  the component body. Backends typically render these as
     #                  a TODO comment block since arbitrary JS-to-Ruby
     #                  translation isn't attempted.
+    # local_binding_names : [String] — flat list of all names bound by the
+    #                  component body (destructure patterns, hook tuples,
+    #                  ordinary const bindings). Backends pass this into the
+    #                  ExpressionTranslator so an identifier reference like
+    #                  `count` resolves to a `nil` placeholder instead of
+    #                  a bare unresolved snake_case identifier that NameErrors
+    #                  at render time. Includes hook destructures (e.g.
+    #                  `open` and `setOpen` from `useState`) even though
+    #                  those names don't appear in `local_bindings`.
     # 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.
+    # react_hooks    : [ReactHookCall] — every recognized hook invocation
+    #                  in the component body, regardless of library.
+    #                  Includes React's built-in hooks (useState, useEffect,
+    #                  useRef, useContext, useMemo, useCallback, useReducer,
+    #                  useImperativeHandle, useLayoutEffect), Apollo hooks
+    #                  (useQuery, useMutation, useLazyQuery, useSubscription,
+    #                  useApolloClient), and Next.js navigation hooks
+    #                  (useRouter, usePathname, useSearchParams, useParams,
+    #                  useSelectedLayoutSegment(s)). Each call carries a
+    #                  `library` tag so backends can group them and emit a
+    #                  library-specific TODO pointing at the right Rails
+    #                  analog (Stimulus/server-render for React; controller
+    #                  fetch for Apollo; request.path/params for Next.js).
+    # module_bindings : [LocalBinding] — top-level `const`/`let` declarations
+    #                  outside the component function that aren't themselves
+    #                  components. Captured so backends can either translate
+    #                  to Ruby constants (literal initializers) or surface
+    #                  as a TODO comment block before the class definition.
+    #                  Without this capture, references to module-level
+    #                  constants from inside the JSX silently drop and
+    #                  produce unbacked snake_case references at render time.
+    # render_methods : [RenderMethod] — local arrow bindings that return JSX
+    #                  and are invoked from the JSX body (`const renderHeader
+    #                  = () => <div/>; ... {renderHeader()}`). Backends emit
+    #                  each as a private method on the generated class and
+    #                  reference it from a LocalRenderCall at the use site.
+    # mode  : Symbol — `:view` for a normal Phlex/ViewComponent component
+    #         whose body is rendered as JSX (the default); `:data_factory`
+    #         for column-descriptor / option-list modules whose top-level
+    #         export is a function returning an array of object literals.
+    #         When `:data_factory`, the backend emits a snake_case method
+    #         that returns the translated data, instead of `view_template`.
+    #         JSX inside object properties still extracts to private
+    #         methods on the class via the IR::Lambda path.
     Component = Data.define(:name, :props, :body, :rest_prop_name,
-                            :local_bindings, :stimulus_methods, :react_hooks) do
+                            :local_bindings, :local_binding_names,
+                            :module_bindings,
+                            :stimulus_methods, :react_hooks,
+                            :render_methods, :mode) do
       include Node
     end
 
@@ -45,22 +85,37 @@ module JsxRosetta
       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".
+    # A hook invocation detected in the component body. Covers React's
+    # built-in hooks plus framework hooks we recognize (Apollo's `useQuery`/
+    # `useMutation`/etc., Next.js's `useRouter`/`usePathname`/etc.).
+    # Surfaced separately from local_bindings so backends can emit a more
+    # specific TODO pointing at the Rails equivalent for each library,
+    # 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
+    # hook      : String — hook function name (`"useState"`, `"useQuery"`, …)
+    # source    : String — verbatim JS of the entire statement.
+    # library   : Symbol — `:react`, `:apollo`, or `:next_js`. Backends
+    #             group hooks by library and emit one TODO block per group,
+    #             since each library maps to a different Rails analog.
+    # operation : String | nil — for Apollo hooks called with a bare-Identifier
+    #             first argument (`useQuery(GET_USERS_QUERY, …)`), the
+    #             captured operation name. nil when the first argument is
+    #             not a simple Identifier, or when the hook isn't Apollo.
+    #             Backends echo it in the TODO so the reviewer can match
+    #             the operation back to its GraphQL document and to the
+    #             Rails controller / model fetch it should become.
+    ReactHookCall = Data.define(:hook, :source, :library, :operation) do
       include Node
     end
 
     # A component prop, possibly with a default value.
     #
-    # name    : String
-    # default : Interpolation | nil
-    Prop = Data.define(:name, :default) do
+    # name       : String — the prop name on the parent (e.g. "data-testid").
+    # default    : Interpolation | nil
+    # alias_name : String | nil — the local binding name inside the body when
+    #              the destructure renames it (`"data-testid": dataTestId`).
+    #              Use sites of the alias resolve to the prop's ivar.
+    Prop = Data.define(:name, :default, :alias_name) do
       include Node
     end
 
@@ -250,11 +305,17 @@ module JsxRosetta
     # 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
+    # name          : String — camelCase Stimulus method name (uniquified
+    #                 when two handlers collide on the same base 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.
+    # original_name : String — the requested base name before uniquification.
+    #                 Equals `name` when there was no collision. When
+    #                 `name != original_name`, backends emit a collision
+    #                 marker comment in the generated controller JS so the
+    #                 reviewer can see the silent rename.
+    StimulusMethod = Data.define(:name, :body_source, :original_name) do
       include Node
     end
 
@@ -272,5 +333,76 @@ module JsxRosetta
     Loop = Data.define(:iterable, :item_binding, :index_binding, :body) do
       include Node
     end
+
+    # An object-literal value (`{ key: value, ... }`) inside JSX. Lowered
+    # from a JSX attribute or expression value whose root is an
+    # ObjectExpression. Each property's key is a String; the value can be
+    # any IR node (recursive). Backends render as a Ruby Hash literal,
+    # snake_casing identifier keys to match Ruby kwarg conventions.
+    #
+    # properties : [[String key, Node value]] — preserved in source order.
+    ObjectLiteral = Data.define(:properties) do
+      include Node
+    end
+
+    # An array-literal value (`[a, b, ...]`) inside JSX. Lowered from a
+    # JSX attribute or expression value whose root is an ArrayExpression.
+    # Each element is an IR node (recursive). Backends render as a Ruby
+    # Array literal.
+    #
+    # elements : [Node]
+    ArrayLiteral = Data.define(:elements) do
+      include Node
+    end
+
+    # An arrow/function expression appearing as an inline value (not in
+    # JSX child or event-handler position). Typical example: a `render`
+    # property inside an array-of-config-objects passed to an AG-Grid
+    # column descriptor or antd Select option. Backends emit as a Ruby
+    # method on the class (deterministically named) and reference it via
+    # `method(:name)` in the value position, since lambdas don't carry
+    # the Phlex execution context required to call tag.* helpers.
+    #
+    # params : [String]
+    # body   : Node
+    Lambda = Data.define(:params, :body) do
+      include Node
+    end
+
+    # A render-prop child: `<Form.List>{(fields) => <div>{fields}</div>}</Form.List>`.
+    # Backends emit this as a Ruby block on the render call, with the params
+    # bound as block arguments. Distinct from Loop (which iterates an
+    # iterable) and from Slot (which yields without args).
+    #
+    # params : [String] — param names (camelCase preserved; backends snake_case).
+    # body   : Node — the lowered IR node produced by the arrow's body.
+    RenderProp = Data.define(:params, :body) do
+      include Node
+    end
+
+    # A locally-declared JSX-returning arrow that's invoked inside the
+    # render body: `const renderHeader = (count) => <h1>{count}</h1>;
+    # ... {renderHeader(headerCount)}`. Backends emit one private method
+    # per RenderMethod on the generated class and reference it via a
+    # LocalRenderCall at each use site.
+    #
+    # name   : String — snake_case method name on the class.
+    # params : [String] — arrow param names (camelCase preserved; backends
+    #          snake_case to form Ruby parameter names).
+    # body   : Node — the lowered IR node produced by the arrow's body.
+    RenderMethod = Data.define(:name, :params, :body) do
+      include Node
+    end
+
+    # A call to a locally-declared JSX-returning arrow at its use site.
+    # Pairs with a sibling RenderMethod on Component#render_methods.
+    #
+    # method_name : String — snake_case method name (matches RenderMethod#name).
+    # args        : [Interpolation] — argument expressions captured verbatim
+    #               (each Interpolation's expression is translated by the
+    #               backend's ExpressionTranslator at emission time).
+    LocalRenderCall = Data.define(:method_name, :args) do
+      include Node
+    end
   end
 end

data/lib/jsx_rosetta/version.rb

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

data/lib/jsx_rosetta.rb

@@ -14,18 +14,19 @@ module JsxRosetta
     IR.lower(ast, source: source)
   end
 
-  def self.translate(source, backend: :view_component, helpers: nil, layout: :sidecar,
-                     typescript: false, source_filename: nil)
+  def self.translate(source, backend: :view_component, backend_options: {},
+                     typescript: false, source_filename: nil, **legacy_options)
     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)
+    backend_instance = backend_for(backend, **legacy_options, **backend_options)
     components.flat_map { |component| backend_instance.emit(component) }
   end
 
-  def self.backend_for(name, helpers: nil, layout: :sidecar)
+  def self.backend_for(name, **options)
     case name
-    when :view_component then Backend::ViewComponent.new(helpers: helpers, layout: layout)
-    when :rails_view then Backend::RailsView.new(helpers: helpers, layout: layout)
+    when :view_component then Backend::ViewComponent.new(**options.slice(:helpers, :layout))
+    when :rails_view then Backend::RailsView.new(**options.slice(:helpers, :layout))
+    when :phlex then Backend::Phlex.new(**options.slice(:suffix, :namespace))
     else
       raise Error, "unknown backend: #{name.inspect}"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsx_rosetta
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Sean McCleary
@@ -28,6 +28,7 @@ files:
 - LICENSE.txt
 - PLAN.md
 - README.md
+- ROADMAP.md
 - Rakefile
 - exe/jsx_rosetta
 - lib/jsx_rosetta.rb
@@ -38,6 +39,7 @@ files:
 - lib/jsx_rosetta/ast/visitor.rb
 - lib/jsx_rosetta/backend.rb
 - lib/jsx_rosetta/backend/base.rb
+- lib/jsx_rosetta/backend/phlex.rb
 - lib/jsx_rosetta/backend/rails_view.rb
 - lib/jsx_rosetta/backend/routes_script.rb
 - lib/jsx_rosetta/backend/view_component.rb
@@ -45,6 +47,7 @@ files:
 - lib/jsx_rosetta/cli.rb
 - lib/jsx_rosetta/ir.rb
 - lib/jsx_rosetta/ir/lowering.rb
+- lib/jsx_rosetta/ir/module_shape_classifier.rb
 - lib/jsx_rosetta/ir/types.rb
 - lib/jsx_rosetta/node_bridge.rb
 - lib/jsx_rosetta/parse_error.rb