jsx_rosetta 0.3.0 → 0.4.0

data/lib/jsx_rosetta/ir/module_shape_classifier.rb

@@ -0,0 +1,148 @@
+# 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
+
+      def class_component?(stmt)
+        decl = stmt.of_type?(*EXPORT_TYPES) ? stmt[:declaration] : stmt
+        AST::Node.matches?(decl, "ClassDeclaration")
+      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,6 +20,15 @@ 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
@@ -30,8 +39,18 @@ module JsxRosetta
     #                  Surfaced as a distinct TODO block so the human
     #                  reviewer knows to translate behavior to Stimulus
     #                  and state to server-side rendering.
+    # 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.
     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) do
       include Node
     end
 
@@ -250,11 +269,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 +297,51 @@ 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
   end
 end

data/lib/jsx_rosetta/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsxRosetta
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 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.4.0
 platform: ruby
 authors:
 - Sean McCleary
@@ -38,6 +38,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 +46,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