jsx_rosetta 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ae2ca5d2ff613e264c7a6027c5a95c57781916a38b52090d6c9d62ba7cafd8c
+  data.tar.gz: 3e6a2e6f2a54e1dd01002e3e1312d3c1144e3af7e315c55cb3eeee137b858c79
+SHA512:
+  metadata.gz: 11b3d8dea5bb887a1b55ebccc0119ce5703bf2c39251a0144dda973d01dd05f7e9b58337fb383e87f3c66d1dfac9a465e6cc5a14dca827e0612073401e4f908c
+  data.tar.gz: 2742e096f9947b4999183e682c0f1f3b405a68894bc9a2bbb4f140fb45f22a5c611c7e5759f88ea9b987bbd98a501f0bbb248638e83b494825881a6ccac60e76

data/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+## [Unreleased]
+
+### Added — translator (lowering)
+
+- **Arrow-function components** — `const X = () => …` (with implicit
+  return or block body), and exported variants. Previously only
+  `function X() { … }` was recognized.
+- **Multi-component files** — `lower_all` walks the entire program body
+  and returns one IR::Component per matched declaration. Backends emit
+  one output pair per component.
+- **Compound component tags** — `<Tabs.List>` lowers as a
+  `ComponentInvocation(name: "Tabs.List")`; the backend renders it as
+  `Tabs::ListComponent.new(...)` (was previously emitting invalid
+  `Tabs.ListComponent.new`).
+- **Spread props** — `JSXSpreadAttribute` lowers to `IR::SpreadAttribute`
+  (replaces the broken `__spread__` placeholder). Component rest-binding
+  (`function X({ a, ...rest })`) captured on `Component#rest_prop_name`.
+- **`asChild` polymorphism** — `const Comp = cond ? Slot : "button"` plus
+  `<Comp/>` synthesizes a Conditional with both branches expanded
+  (Element for string-literal tags, ComponentInvocation for identifiers).
+- **`cn()` / `clsx()` / `classnames()`** — recognized at lowering time;
+  decomposed into IR::ClassList with literal segments, identifier
+  interpolations, and conditional segments from object-literal arguments.
+- **Inline styles** — `style={{ fontSize: 12 }}` lowers to IR::Style with
+  kebab-case property names; identifier values become Interpolations.
+- **Local JSX const inlining** — `const image = <Image .../>; <div>{image}</div>`
+  inlines the JSX at the use site (also through ternary branches).
+- **Local non-JSX `const` bindings** — preserved verbatim in a
+  `<%# TODO: translate JS to Ruby %>` block at the top of the rendered
+  template (not auto-translated; see policy note below).
+- **React hooks detection** (`useState`, `useEffect`, `useRef`,
+  `useContext`, `useMemo`, `useCallback`, `useReducer`,
+  `useImperativeHandle`, `useLayoutEffect`, `useDebugValue`) — surfaced
+  in their own TODO block pointing at the Hotwire/Stimulus alternative.
+  Both `const [x, setX] = useState(...)` and bare `useEffect(...)`
+  ExpressionStatements are captured.
+- **Stimulus method extraction** — inline arrow event handlers
+  (`onClick={() => …}`) and const-bound arrow handlers referenced from
+  `onX={…}` lower to IR::StimulusBinding + IR::StimulusMethod. Backend
+  emits a sibling `_controller.js` skeleton with the original JS body
+  preserved as a comment.
+- **Literal expression containers** — `{"foo"}`, `{42}` lower to plain
+  text instead of `<%= "foo" %>`. `{true}` / `{null}` are dropped
+  (matches React's runtime).
+- **JSX comments** — `{/* foo */}` lowers to IR::Comment; renders as
+  `<%# foo %>`.
+- **JSX text whitespace normalization** — Babel's
+  `cleanJSXElementLiteralChild` algorithm. Removes the indented blank
+  lines that previously surrounded inline text.
+- **Void element handling** — `<img />`, `<hr />`, `<br />`, `<input />`,
+  etc. self-close; no spurious closing tag.
+- **`key={…}` dropped** on both ComponentInvocation and Element (it's a
+  React-only reconciliation hint, not a DOM attribute).
+- **JSX member chains snake-cased** — `post.coverImage` → `@post.cover_image`
+  (each chain segment, not just the root).
+- **Template literals with member chains** — `` `/posts/${post.id}` `` →
+  `"/posts/#{@post.id}"` (was previously flagged as TODO).
+- **Unary expressions** — `!preview`, `-x`, `+x`, `!!flag` translate
+  through to Ruby (`!@preview` etc.).
+- **Lowering errors** carry line/column from the failing AST node.
+
+### Added — backends
+
+- **`Backend::ViewComponent`**:
+  - **Sidecar layout** (default) per ViewComponent's `--sidecar`
+    generator: `.rb` at the top level, `.html.erb` and any sibling
+    Stimulus controller in a `<snake>_component/` subdirectory. Pass
+    `layout: :flat` for the previous flat layout.
+  - **Helper-call mapping** — `<Link>` → `link_to(...)`, `<Image>` →
+    `image_tag(...)`. Override or extend via the `helpers:` kwarg;
+    disable entirely with `helpers: false`.
+  - **Element tag-builder mode** — switches to Rails' `tag.button(...)`
+    builder when a SpreadAttribute is present on an HTML element
+    (literal HTML stays for the no-spread case).
+  - **Hyphenated kwargs** on ComponentInvocations emit as quoted-key
+    hash entries (`"aria-label" => @x`) so they're valid Ruby.
+  - **Initializer with `**rest`** when the source destructures a rest
+    binding.
+  - **Inlined attribute interpolation** — `href="/posts/<%= @slug %>"`
+    instead of `href="<%= "/posts/#{@slug}" %>"` (template-literal
+    inlining, previously only applied to className).
+  - **Unresolved-identifier flagging** — interpolations whose translator
+    result reports an unresolved name get a `<%# TODO: unresolved
+    identifier "X" %>` marker.
+
+- **`Backend::RailsView`** (new) — emits a single `<snake>.html.erb`
+  with no Ruby class and no sidecar dir. Appropriate for pages tied to
+  a route. Pass `--as=view` on the CLI or `backend: :rails_view` in the
+  API. Stimulus controllers still emit alongside when applicable.
+
+- **`Backend::RoutesScript`** (new) — turns IR::RouteTree into a
+  reviewable Ruby script with `system "rails", "generate", "controller"`
+  invocations and a suggested `config/routes.rb` block.
+
+### Added — routes subcommand
+
+- **`jsx_rosetta routes <input>`** parses `<Routes><Route>` JSX and
+  emits the routes script. Member-expression element references
+  (`<Layout.Home />`) flatten to the rightmost name. Recognized
+  patterns: `path` is a string literal (`path="/x"` or `path={"/x"}`);
+  `element` is a JSX element.
+- **Resource consolidation** — `/xs` + `/xs/:id` pairs collapse into
+  `resources :xs, only: %i[index show]` with a single
+  `rails generate controller xs index show` call.
+- **Catch-all routes** — `<Route path="*">` emits
+  `match "*path", to: …, via: :all` (bare `*` is normalized to `*path`).
+- **Reserved-name collision warning** — when a generated controller
+  name matches a Rails reserved term, the script flags it.
+
+### Added — IR types
+
+`IR::SpreadAttribute`, `IR::ClassList`, `IR::ConditionalSegment`,
+`IR::Style`, `IR::StyleDeclaration`, `IR::Comment`, `IR::LocalBinding`,
+`IR::StimulusBinding`, `IR::StimulusMethod`, `IR::ReactHookCall`,
+`IR::RouteTree`, `IR::RouteEntry`. `IR::Component` gains
+`rest_prop_name`, `local_bindings`, `stimulus_methods`, and
+`react_hooks` fields.
+
+### Translation policy
+
+- **Don't translate arbitrary JS to Ruby.** Bindings whose RHS isn't
+  one of the narrowly-recognized shapes (literals, identifiers,
+  member chains, simple template literals, `cn()`-style calls,
+  inline-style object literals) get preserved verbatim in a TODO
+  comment block. Speculative translation produced broken Ruby that
+  looked plausible — worse than an obvious TODO.
+- **Behavioral JS → Stimulus controllers.** Inline event-handler arrows
+  extract to a generated `_controller.js` skeleton; `data-action`
+  descriptors get auto-wired.
+- **React hooks → Hotwire/Stimulus + server-side rendering.** Detected
+  but not auto-translated; surfaced in a distinct TODO with
+  alternatives noted.
+
+### Verified end-to-end
+
+- `vercel/next.js` `examples/blog-starter` — 15/16 components translate
+  cleanly; the one failure (`theme-switcher.tsx`) uses
+  `memo`+`useState`+`useEffect` and is structurally out of scope.
+- A multi-route React Router app translates into a Rails 8.1 app with
+  five routes (Home, PostsIndex, PostShow, About, NotFound)
+  end-to-end. See `app/views/<controller>/<action>.html.erb` placement
+  via `--as=view`.
+
+## [0.1.0] - 2026-05-09
+
+- Initial release. Phases 0–6: AST, IR, ViewComponent backend, slots,
+  conditionals, events, loops, CLI.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"jsx_rosetta" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["seanmcc@gmail.com"](mailto:"seanmcc@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sean McCleary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PLAN.md

@@ -0,0 +1,236 @@
+# jsx_rosetta — Implementation Plan
+
+> **Status (2026-05-10):** Phases 0–6 below are all shipped. Work after
+> Phase 6 (arrow components, spread props, cn/clsx, Stimulus extraction,
+> sidecar layout, helper mappings, RailsView backend, routes subcommand,
+> compound components, asChild polymorphism, React hooks detection, …)
+> is described in [CHANGELOG.md](CHANGELOG.md) — preserved here as
+> historical context for the original v0.1.0 design.
+
+`jsx_rosetta` is a Ruby gem that translates JSX into Rails ViewComponent
+(Ruby class + ERB template) via a three-stage pipeline. Other output
+formats (Phlex, Slim, Phoenix LiveView, etc.) are anticipated by design
+and accommodated by the IR — adding one is a new backend, not a rewrite.
+
+## Pipeline
+
+```
+JSX text ──► Babel AST ──► Ruby AST ──► IR ──► ViewComponent backend ──► .rb + .html.erb
+            (Node + Babel) (Ruby tree)  (sema)  (string-built ERB + Ruby)
+```
+
+## Architectural decisions (locked)
+
+- **JSX parsing:** Shell out to a Node sidecar running `@babel/parser`.
+  No native JS engine in the Ruby process.
+- **Node dependencies:** Not vendored. `node/package.json` declares deps;
+  `node/node_modules/` is gitignored. The gem provides an install
+  command (`jsx_rosetta install`) that runs `npm install` for the user.
+- **AST:** Typed Ruby classes mirroring Babel node shapes 1:1. The gem
+  does not normalize at the AST layer — that's the IR's job.
+- **IR:** Required. Framework-agnostic, semantic. The multi-backend
+  abstraction lives here. Nothing in the IR mentions Ruby, ERB, or Rails.
+- **Initial backend:** ViewComponent (one `.rb` class + one `.html.erb`
+  per JSX component).
+- **ERB writer:** String-built in Ruby. Optional structural validation
+  via the `herb` gem in tests. Migrate to programmatic Herb construction
+  only if string-building causes real pain.
+- **No RBS.** Skeleton `sig/` directory removed.
+- **Fixtures:** `spec/fixtures/jsx/` for JSX inputs,
+  `spec/fixtures/expected/` for golden output files.
+
+## Project layout
+
+```
+lib/jsx_rosetta/
+  version.rb
+  parser.rb              # public entry: JSX text → AST::Program
+  node_bridge.rb         # subprocess plumbing
+  parse_error.rb
+  ast/
+    node.rb              # base, with deconstruct_keys for pattern matching
+    builder.rb           # JSON hash → typed nodes
+    visitor.rb
+    <one-per-type>.rb
+  ir/
+    node.rb
+    lowering.rb          # AST::Program → IR::Component
+    <one-per-type>.rb
+  backend/
+    base.rb              # backend interface; pluggable
+    view_component.rb    # IR::Component → { ruby:, erb: }
+  cli.rb                 # exe/jsx_rosetta dispatch
+node/
+  package.json
+  parse.js               # stdin (JSX) → stdout (JSON AST)
+  .gitignore             # node_modules/
+spec/
+  parser_spec.rb
+  ast/{builder,visitor}_spec.rb
+  ir/lowering_spec.rb
+  backend/view_component_spec.rb
+  fixtures/
+    jsx/{button,dialog,combobox}.{jsx,tsx}
+    expected/{button,dialog,combobox}.{rb,html.erb}
+exe/jsx_rosetta
+```
+
+## Components
+
+### Node sidecar (`node/`)
+
+- `package.json` — declares `@babel/parser` as the only runtime dep.
+- `parse.js` — reads a JSON request from stdin (`{ source, typescript,
+  source_filename }`), runs `@babel/parser`, writes a JSON response to
+  stdout. Errors surface as `{ error: { message, line, column } }`.
+- `node_modules/` — gitignored. Users install via `jsx_rosetta install`.
+
+### Parser (`lib/jsx_rosetta/parser.rb`)
+
+```ruby
+JsxRosetta::Parser.new.parse(source, typescript: false) # => AST::Program
+```
+
+- Locates `node` on `PATH`, with `JSX_ROSETTA_NODE` env override.
+- Spawns the sidecar via `Open3.capture3` (one-shot mode for MVP).
+- Parses the JSON response and hands it to `AST::Builder`.
+- A long-lived worker (newline-delimited base64-framed requests) is a
+  Phase 6 optimization, not a Phase 0 concern.
+
+### AST (`lib/jsx_rosetta/ast/`)
+
+- `Node` base — `type`, `loc`, `range`, `children`, `deconstruct_keys`.
+- Typed subclasses for each Babel node type the corpus actually uses.
+  Start narrow; expand as fixtures demand. Unknown types fall through to
+  a generic `Node` so we don't crash on ESNext additions.
+- `Builder.build(json_hash) → Node` — factory dispatching on `type`,
+  recursing into children.
+- `Visitor` — `visit(node)` dispatches to `visit_<TypeName>`,
+  default-recurses children.
+
+### IR (`lib/jsx_rosetta/ir/`)
+
+Initial node types (expanded by phase as fixtures require):
+
+```
+Component       { name, props[], slots[], body }
+Element         { tag, attributes[], children[] }
+Text            { value }
+Interpolation   { expression }              # opaque token, emitted verbatim
+Loop            { iterable, item, index?, body }
+Conditional     { test, consequent, alternate? }
+ComponentInvocation { name, props[], children[] }
+Fragment        { children[] }
+Attribute       { name, value }             # literal or Interpolation
+EventBinding    { event, handler }          # onClick, onChange — backend decides
+Slot            { name }                    # children prop or named slot
+StyleBinding    { classes[], conditional[] } # className={cn(...)} lowered here
+```
+
+`Lowering.lower(ast_program) → IR::Component` is the AST→IR pass. It
+normalizes JSX-specific patterns: the three "render-if" forms
+(`{cond && x}`, `{cond ? x : null}`, `{cond ? x : y}`) all collapse to
+one `Conditional`. JS expressions stay as opaque tokens during MVP —
+they're emitted verbatim into ERB and flagged with a comment when
+non-trivial.
+
+### Backend (`lib/jsx_rosetta/backend/`)
+
+- `Base` — interface every backend implements:
+  ```ruby
+  Backend::Base.new.emit(ir_component) # => { files: [{ path:, contents: }, ...] }
+  ```
+  Pluggable from day one so adding Phlex/Slim/LiveView later is mechanical.
+- `ViewComponent` — string-builds the `.rb` class and `.html.erb`
+  template. Optional: parse the emitted ERB with the `herb` gem in
+  tests as a structural sanity check.
+
+### CLI (`exe/jsx_rosetta`)
+
+- `jsx_rosetta install` — runs `npm install` in the gem's vendored
+  `node/` directory.
+- `jsx_rosetta translate input.jsx --backend=view_component --out dir/` —
+  end-to-end translation.
+- `jsx_rosetta parse input.jsx` — emit the parsed AST as JSON. Useful
+  for debugging fixtures.
+
+## Phases
+
+### Phase 0 — Node sidecar + Ruby round-trip
+
+- Scaffold `node/` with `package.json`, install `@babel/parser`,
+  gitignore `node_modules`.
+- Write `node/parse.js` (one-shot mode).
+- `JsxRosetta::Parser#parse` calls the sidecar, returns the parsed
+  JSON as a nested Hash (no typed nodes yet).
+- Drop `spec/fixtures/jsx/button.jsx`.
+- Specs: parser returns a Program containing the expected JSXElement;
+  `ParseError` surfaces line/column on invalid JSX.
+- Strip the gemspec's TODO placeholders; delete `sig/`.
+
+### Phase 1 — Typed AST + visitor
+
+- `AST::Node` base + Babel node subtypes Button uses.
+- `AST::Builder` factory; pattern-match support on nodes.
+- `AST::Visitor` with default recursion. Spec: visitor collects every
+  JSXElement tag from Button.
+
+### Phase 2 — IR + lowering for Button
+
+- IR node types Button needs (`Component`, `Element`, `Attribute`,
+  `Interpolation`, `StyleBinding`, `ComponentInvocation`).
+- `Lowering` pass producing IR from AST for Button.
+- Spec: parsing Button JSX yields the expected IR tree.
+
+### Phase 3 — ViewComponent backend, end-to-end Button
+
+- `Backend::Base` interface.
+- `Backend::ViewComponent` for the Button IR subset.
+- Hand-write `spec/fixtures/expected/button.rb` and `button.html.erb`.
+- Golden-file test: `JsxRosetta.translate(button.jsx)` matches the
+  expected files. **First end-to-end vertical slice.**
+
+### Phase 4 — Dialog: state, events, slots
+
+- IR additions: `EventBinding`, `Slot`, `Conditional`. Lowering for
+  compound components.
+- ViewComponent backend learns slots, derived state (lowered to
+  component methods), Stimulus `data-action` / `data-controller` /
+  `data-target` attributes for events and refs.
+- Decide where the Stimulus runtime lives (likely a sibling JS package,
+  out of this gem's scope but referenced by the README).
+
+### Phase 5 — Combobox: keyboard nav + list rendering
+
+- IR addition: `Loop`. Lowering for `.map(...)` patterns.
+- More Stimulus controller surface (combobox, keyboard-nav, focus-trap).
+
+### Phase 6 — DX polish
+
+- `jsx_rosetta install` CLI command and helpful "Node missing /
+  `@babel/parser` not installed — run `bundle exec jsx_rosetta install`"
+  errors.
+- Long-lived Node worker (newline-delimited base64-framed JSON) when
+  parsing many files matters.
+- README rewrite. `bin/setup` runs `npm install` in `node/`.
+- Optional: structural validation of emitter output via the `herb` gem.
+
+## Deferred questions
+
+1. **Stimulus runtime packaging** — same repo, sibling gem, or JS
+   package? Decide before Phase 4.
+2. **CVA / tailwind-variants** — for MVP, pass `cn(...)` through as a
+   flagged interpolation. Build-time evaluation can come later.
+3. **Worker framing protocol** — only matters when batch parsing matters
+   (Phase 6).
+4. **Migrating ERB emission to Herb** — only if string-built ERB causes
+   real pain.
+
+## Non-goals
+
+- Translating arbitrary React codebases. The MVP is component-library-shaped input.
+- Translating React data-fetching (`react-query`, SWR, Suspense). Flag for manual review.
+- Translating React Router. Out of scope.
+- Runtime JS-to-Ruby translation of arbitrary expressions. Pass through and surface for human review.
+- Round-tripping (ERB → JSX). One direction only.
+- Perfect visual parity. Structural and behavioral parity is the bar; visual tweaks may be needed.