jsx_rosetta 0.3.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28709ed22159e135331acff12df2c1fadbc2b692c62cd90d40a977192b28a46d
-  data.tar.gz: 4c8543a43d7ca8e96ba3c93d92f89fddbb548d4329332487df67683cabffa4e9
+  metadata.gz: 229956b183e3760f9555874fef214d7ce66d549a603e9d431f5c28251db25bb4
+  data.tar.gz: 226c173f5e1010d154801740a2924bbc776ff8eede26587ec1d9d796da51c5f1
 SHA512:
-  metadata.gz: c053e3111f0dc98f5ce3549d0c50a06f04f69bdbb13f5206296e807c62174b1e3824c9ac30d327884c20d1dd39d4fa821bec931292ff9802343b7d8c6a1da1ce
-  data.tar.gz: d06787398b3c56482c881184f0cdcbe6ce20071c9c6a1d1cc411fad1514a5a4910d9d7ddfd78455107e14f4285fdf4dcf2299f42a48622790bccb9c7d02bfc17
+  metadata.gz: 4dbf8ac15094f2462a38c65dfbf539163cfb471077e4bd8874893eda3262da031df72da161793f4c65d75597d55c1d7ea09b395f991fb7fcf80b074d6a74e7ca
+  data.tar.gz: 94627c0471abeab22e92727047ec9e870439297bc6df6447da1bfb79914415d14abc665d3b2325d9496615e62c3f0099898db11a6c05dfd37acf739aa0af518c

data/CHANGELOG.md

@@ -1,5 +1,339 @@
 # Changelog
 
+## [0.5.1] - 2026-05-11
+
+A correctness pass on the v0.5.0 Phlex output. A random-sample review
+surfaced six classes of render-time NameError that `ruby -c` couldn't
+catch (the file parses, but evaluation crashes on a bare reference).
+Each one is now closed at the source — the file loads and at worst
+renders empty where a TODO marker tells the reviewer what to fill in.
+Stress test stays at 895/929 clean and 0/1240 syntax failures; lint
+volume on the generated `.rb` files drops ~38% (5443 → 3373 offenses).
+
+### Fixed — runtime NameErrors at render time
+
+- **Destructure leaks downstream of an untranslatable init.** `const
+  { fieldValue } = customField` is captured as a TODO, but every use
+  site (`fieldValue?.X`, `!fieldValue`, `fieldValue > 0`) used to leak
+  as a bare snake_case ref — file loaded, but `field_value&.__typename`
+  NameErrored on first render. The translator now bails the whole
+  expression when a known-local sits at a member-chain root, on the
+  operand side of unary, or on either side of binary. The caller emits
+  a `# TODO: translate condition: …` line and falls through to an
+  `if false` fallback so the file at least loads.
+- **Inline arrow handlers on PascalCase components.** `const handleClick
+  = () => {}` attached to `<Button onClick={handleClick}>` no longer
+  leaks as bare `handle_click`. Unconsumed local-arrow names are unioned
+  into `Component#local_binding_names`, so use sites emit `on_click: nil`
+  instead of a reference to an undefined method.
+- **CamelCase / snake_case rest-prop mismatch.** `**descriptionProps`
+  emitted `**descriptionProps` in the initializer signature but the body
+  read `**(@description_props || {})` — silently dropped. The rest-name
+  is now snake_cased on both sides. `IR::Prop` gains an `alias_name:`
+  field so renamed destructures (`"data-testid": dataTestId`) resolve
+  the alias to the prop's snake_case ivar at use sites.
+- **Unitless numeric inline styles.** `style={{ marginBottom: 16 }}` used
+  to emit `style: 'margin-bottom: 16;'` — invalid CSS, silently ignored
+  by browsers. Numeric style values now get a `px` suffix for any
+  property not in React's `isUnitlessNumber` table (`zIndex`,
+  `lineHeight`, `opacity`, etc. stay bare).
+- **Style declarations rooted at an unresolvable local.** `style={{
+  borderRadius: token.borderRadius }}` used to emit `"border-radius:
+  #{token.borderRadius};"` and NameError at render. The style
+  declaration now drops with a per-decl TODO when its value can't
+  translate.
+- **Uppercase / SCREAMING_SNAKE imports in attribute values.** JSX
+  `<Foo bar={DEFAULT_PAGE_SIZE}>` used to emit `bar: default_page_size`
+  (NameError at the call site). Attribute-position interpolation now
+  drops with a TODO when any unresolved identifier starts with
+  uppercase — almost always an external import. Lowercase unresolved
+  identifiers still pass through unchanged (they may be Rails helpers
+  like `current_user`).
+
+### Changed — rubocop output cleanup (5443 → 3373 offenses across 1240 .rb)
+
+- **`Lint/MissingSuper`** — initializers emit `super()` to satisfy
+  Phlex 2.x's superclass.
+- **`Style/Documentation`** — one-line class docstring above every
+  generated class (`# X — generated by jsx_rosetta from JSX. Review
+  before shipping.`).
+- **`Style/StringLiterals`** — new helper `AST::Inflector.ruby_string_literal`
+  emits single-quoted strings when safe (no embedded single quote,
+  backslash, or control char). Non-ASCII like emojis stays in single
+  quotes. The translator also re-emits JS string literals (`"hi"` →
+  `'hi'`) when the same constraints hold.
+- **`Style/NilComparison` / `Style/NonNilCheck`** — rewrite `x == nil`
+  and `x != nil` as `x.nil?` / `!x.nil?` at the binary-translation
+  layer.
+- **`Lint/BinaryOperatorWithIdenticalOperands`** — dedupe `||` / `&&`
+  when both sides translate to the same Ruby. `value === null ||
+  value === undefined` collapses to `@value.nil?` instead of
+  `@value.nil? || @value.nil?`.
+- **`Lint/EmptyInterpolation`** — bail on the whole template literal
+  when any interpolation segment fails translation or resolves to
+  literal `nil`. No more `"prefix-#{}-suffix"`.
+- **`Lint/LiteralAsCondition` / `Lint/DuplicateElsifCondition`** —
+  emit a file-level `# rubocop:disable` directive (with a matching
+  enable at the bottom of the file) only when an intentional `if false`
+  fallback appears. The `# TODO: translate condition:` line above the
+  fallback already names the issue, so the cop's report would be
+  redundant noise.
+- **`Style/IfInsideElse`** — refactor conditional rendering to chain
+  `if / elsif / elsif / else / end` instead of nested
+  `if / else / if / else / end`. Cascades into fewer
+  `Metrics/BlockNesting`, `Metrics/AbcSize`, and
+  `Lint/DuplicateElsifCondition` offenses too.
+- **`Layout/TrailingWhitespace`** — post-process emitted output to
+  rstrip every line.
+- **`Layout/FirstHashElementIndentation`** — force-inline object/array
+  literals inside `initialize` default values; the column mismatch
+  that triggered the cop only happens when the wrap kicks in there.
+
+## [0.5.0] - 2026-05-11
+
+Closes the four v0.5.0-candidate items from the v0.4.0 Phlex sample
+review, plus the four larger features queued at the top of the
+roadmap: Apollo + Next.js hook hint translation, class-component
+support, AG-Grid column-descriptor module emission, and pretty-printing
+for long object/array literals.
+
+### Added — class-component support
+
+- **`ClassDeclaration` → ViewComponent path.** Classes with a `render()`
+  method now lower as components instead of getting flagged with the
+  `:class_component` rejection. The `ExpressionTranslator` recognizes
+  `this.props.X` and translates to `@x` (plus a snake_case member chain
+  for `this.props.X.y.z`); `this.state.X` translates to `nil` since
+  there's no Rails-side equivalent without a backing data source. Other
+  class members (constructor, lifecycle hooks like
+  `componentDidCatch`/`getDerivedStateFromError`, custom event handlers)
+  get captured as LocalBinding-style TODO comments at the top of the
+  view template so the reviewer sees the verbatim sources. Props are
+  synthesized from direct `this.props.X` access AND from
+  `const { X } = this.props` destructure patterns — the generated
+  `initialize(...)` matches the original class's prop set.
+  Stress-test impact: the 4 class-component residuals (ErrorBoundary
+  and cousins) now translate cleanly.
+
+### Added — AG-Grid column-descriptor module emission
+
+- **Data-factory components.** `export const createColumns = (token,
+  sortedInfo) => [{...}, {...}]` now lowers as an `IR::Component` with
+  `mode: :data_factory`. Phlex emits a snake_case method that returns
+  the translated array — `def create_columns(token: nil, sorted_info: nil)`
+  — instead of `view_template`. JSX inside object properties extracts to
+  private methods on the class via the existing IR::Lambda path
+  (`render: method(:render_id_cell)`). ViewComponent backend emits a
+  plain Ruby class with the method and a TODO note (the .erb pair is
+  skipped — pure-data classes don't have a template). Multi-positional
+  Identifier params are now also supported by `lower_params` — previously
+  only single-arg React-style signatures lowered cleanly.
+
+### Added — pretty-printing
+
+- **Multi-line layout for long object/array literals.** When the single-
+  line rendering of an `IR::ObjectLiteral` or `IR::ArrayLiteral` exceeds
+  `LITERAL_INLINE_BUDGET` (80 chars), or contains a nested literal that
+  itself wrapped, the layout switches to one entry per line indented
+  two spaces past the parent line's indent. Closing bracket re-aligns
+  to the parent indent. Short literals (typical Select options, small
+  config objects) stay inline so non-AG-Grid output is unchanged. Helps
+  readability of the column-descriptor output from the new
+  data-factory path.
+
+### Stress test outcome
+
+- 929-file Phlex stress rerun: **895/929 clean translations**
+  (up from 887/929 in v0.4.0 — 8 additional files now translate via
+  the class-component and data-factory paths). **0/1240 emitted `.rb`
+  files fail `ruby -c`** (unchanged; 16 more files emitted vs v0.4.0).
+  221/929 files carry an Apollo TODO block (281 GraphQL operation
+  names captured); 105/929 carry a Next.js navigation-hook block.
+- 385 specs, all green; rubocop clean.
+
+### Added — framework hook hints
+
+- **Apollo data-fetching hooks recognized.** `useQuery`, `useLazyQuery`,
+  `useMutation`, `useSubscription`, and `useApolloClient` are now
+  detected at lowering time. Each call lands in `Component#react_hooks`
+  tagged `library: :apollo`, with the GraphQL operation name extracted
+  from a bare-Identifier first argument (`useQuery(GET_USERS_QUERY, …)`
+  → `operation: "GET_USERS_QUERY"`). Both backends emit a dedicated
+  Apollo TODO block above the template that points at the Rails analog
+  (move the fetch to the controller; mutations become form POSTs or
+  Turbo Stream responses). Operation names are echoed in the comment so
+  the reviewer can match the call back to its GraphQL document.
+  Destructured names (`{ data, loading, error }` from `useQuery`,
+  `[mutate, { loading }]` from `useMutation`) are captured in
+  `local_binding_names` so use sites translate to `nil` placeholders
+  instead of raising NameError at render time.
+- **Next.js navigation hooks recognized.** `useRouter`, `usePathname`,
+  `useSearchParams`, `useParams`, `useSelectedLayoutSegment`, and
+  `useSelectedLayoutSegments` get the same treatment — tagged
+  `library: :next_js`, surfaced in a dedicated TODO block listing each
+  hook's Rails equivalent (`useRouter` → `redirect_to`; `usePathname`
+  → `request.path`; `useSearchParams` / `useParams` → `params`;
+  `useSelectedLayoutSegment(s)` → pattern-match `request.path`).
+
+The `ReactHookCall` IR type gains `library` and `operation` fields;
+both backends group hooks by library and emit one TODO block per group.
+React-only files keep the unchanged single-block output.
+
+### Added
+
+- **`BinaryExpression` and `LogicalExpression` translation.**
+  `email.emailAttachments.length > 0` now translates to
+  `@email.email_attachments.length > 0` instead of bailing to `if false`.
+  Covers `===`/`!==`/`==`/`!=`/`<`/`>`/`<=`/`>=`/`&&`/`||`/`??`. JS-only
+  operators map to their Ruby equivalents (`===` → `==`, `??` → `||`).
+  Recursive splitting respects nested parens and string literals; outer
+  parens are stripped so `(a > b) && c` parses cleanly.
+- **Optional chaining (`?.`) → safe navigation (`&.`).** `user?.profile?.name`
+  now emits `@user&.profile&.name` instead of leaving a Ruby SyntaxError
+  in member-chain interpolations.
+- **Nested render-function locals extracted to methods.**
+  `const renderHeader = () => <h1/>; ... {renderHeader()}` previously
+  dropped to `[untranslated: renderHeader()]`. New IR types `RenderMethod`
+  and `LocalRenderCall` mean the arrow gets extracted to a private method
+  on the Phlex class (`def render_header; h1 do; ...; end`) and the use
+  site emits a direct call. Args translate through the same path as
+  attribute interpolations. The ViewComponent backend emits a method
+  skeleton with a TODO since ERB-method bodies don't translate cleanly
+  to Ruby fragments.
+
+### Fixed
+
+- **`useCallback` / `useRef` / `useMemo` identifier bindings recognized.**
+  `const handleChange = useCallback(...)` followed by
+  `onChange={handleChange}` used to emit `on_change: handle_change`
+  referencing a nonexistent method. The binding name is now captured in
+  `Component#local_binding_names` so the translator emits `nil` at use
+  sites, matching the destructure-pattern behavior added in v0.4.0.
+- **Conditional guard on a known local no longer collapses to `if nil`.**
+  `error && <X />` where `error` is destructured from a hook used to
+  translate to `if nil` (the local-binding placeholder) — Ruby-valid but
+  silently never-rendering. Both backends now treat a `"nil"` translation
+  as untranslatable, falling through to the TODO-emission path so the
+  reviewer sees what to fill in.
+
+## [0.4.0] - 2026-05-11
+
+Closes nine translation gaps identified during a sample review of 12
+random Phlex outputs from the v0.3.0 stress run. Each gap was a silent
+drop, a render-time NameError, or a semantic mistranslation — the
+generated Ruby parsed but didn't behave like the source JSX.
+
+### Added
+
+- **Render-prop / function-as-children support.**
+  `<Form.List>{(fields) => <p>{fields}</p>}</Form.List>` now lowers to a
+  new `IR::RenderProp` and emits as a Ruby block on the parent `render`
+  call: `render Form::List.new do |fields| ... end`. Both Phlex and
+  ViewComponent backends emit the block; param names snake_case to match
+  Ruby convention. Previously dropped as `plain "[untranslated: ...]"`.
+- **Recursive object/array/lambda translation in attribute values.**
+  New IR types `ObjectLiteral`, `ArrayLiteral`, and `Lambda` mean that
+  `<Select options={[{ value: 10, label: "10 / page" }]} />` now emits
+  `options: [{ value: 10, label: "10 / page" }]` (Ruby array of hashes)
+  instead of `options: nil` with a TODO. Identifier keys snake_case
+  (`dataLabel` → `data_label`); nested literals recurse. Function-valued
+  properties — e.g. AG-Grid `render: (v) => <Tag>{v}</Tag>` — extract to
+  private methods on the class (`def render_render(v); span do; ...; end`)
+  and the property emits as `render: method(:render_render)` so the
+  body has access to the Phlex tag.* helpers.
+- **Module-level constants captured into `Component#module_bindings`.**
+  `const FOO = 400; function X() { return <p>{FOO}</p>; }` no longer
+  silently drops the FOO declaration — the backend emits a TODO comment
+  block above the class with the original source so the reviewer either
+  translates it to a Ruby constant or moves it to a Rails initializer.
+- **Destructure-pattern names recognized by the translator.**
+  `const [count, setCount] = useState(0); <p>{count}</p>` previously
+  emitted a bare `plain count` that NameErrored at render time. The
+  destructured names are now captured in `Component#local_binding_names`
+  and the `ExpressionTranslator` emits a `nil` placeholder for them so
+  the file at least loads. Covers `ArrayPattern`, `ObjectPattern`
+  (including aliased properties, `AssignmentPattern` defaults, and
+  `RestElement`), and hook-tuple destructures.
+- **Member-expression destructure resolution.** `const { Content } = Layout`
+  followed by `<Content/>` now resolves to `Layout::Content`, not a
+  free-floating `ContentComponent`. Multiple destructured names from the
+  same parent identifier all resolve correctly.
+
+### Fixed
+
+- **Component-prop callbacks no longer over-promote to Stimulus.**
+  `<Select onChange={onChange} />` (PascalCase tag) previously emitted
+  `data-action="change->foo#onChange"` — a Stimulus action descriptor
+  that never fires because the receiving component is a Ruby class, not
+  a DOM element. The lowering now checks `html_element?(tag)` before
+  promoting `on*` attrs and treats component-prop callbacks as regular
+  `IR::Attribute` kwargs. Stimulus promotion still applies to lowercase
+  HTML tags as before. Closes a regression introduced by the v0.3.0
+  prop-handler Stimulus promotion.
+- **Spread-of-nil no longer raises at render time.** `<div {...maybeNil}>`
+  used to emit `**@maybe_nil`, which raises when the prop is `nil`. Both
+  Phlex and ViewComponent backends now wrap as `**(@maybe_nil || {})`.
+  Cheap to emit unconditionally and idempotent.
+- **Duplicate handler names are no longer silently renamed.** Two
+  `onClick={handleReset}` handlers in one component previously produced
+  `handleReset` / `handleReset2` with no marker. `StimulusMethod` now
+  carries an `original_name` field, and the generated controller JS
+  emits a `// NOTE: method renamed from "handleReset"` comment above the
+  renamed method.
+- **ReactNode-typed props get a `raw` hint comment.** When an
+  interpolation translates to a bare `@ivar` reference (likely a prop),
+  the Phlex backend emits a comment hint —
+  `plain @extra # NOTE: use \`raw\` instead of \`plain\` if this is a
+  ReactNode-typed prop`. `plain` HTML-escapes its argument, which is
+  wrong for prebuilt-markup props but right for strings; we can't tell
+  at translation time, so we default to safe (`plain`) and surface the
+  choice.
+
+### Investigation
+
+- **Sibling named exports — not a gap.** Probed four shapes of
+  `export default Foo; export function Loading() {}` against the gem;
+  all four shapes correctly emit both `foo.rb` and `loading.rb`. Closed
+  the suspected gap as a false positive from the random sample.
+
+### Refactored
+
+- `Lowering` class shrunk by ~150 lines (v0.3.0 prep, now shipping):
+  pure-heuristic `ModuleShapeClassifier` lives in its own file; helper
+  methods `AST::Node#child`, `#of_type?`, `Node.matches?` replaced ~25
+  defensive `is_a?(AST::Node) && type ==` checks; class/style rendering
+  in the ViewComponent backend deduplicated across HTML-vs-Ruby output
+  formats; `tag_builder_data_action` replaced its "parse what I just
+  emitted" heuristic with a structured `EventDescriptor` intermediate.
+
+### Stress test outcome
+
+- 929-file Phlex stress run on `reserv-web`: 887/929 clean translations
+  (unchanged — rejection logic untouched), **0/1224 syntax failures**
+  (down from 25 on v0.3.0). All emitted `.rb` files now pass `ruby -c`.
+- Five residual bugs were caught during the v0.4.0 stress rerun and
+  fixed inline:
+  - Prop default expressions that translated to `nil # TODO: ...` inside
+    `initialize(...)` swallowed the closing `)`. Prop defaults now route
+    through the same recursive lowering as attribute values.
+  - Multi-line JSX comments only prefixed the first line with `#`. Every
+    line of a comment now gets a `#` prefix.
+  - Template literals with inner `"` or `\\` characters could break the
+    surrounding Ruby string. Literal segments now escape both.
+  - `token.blue` (where `token` was a captured local binding) translated
+    to `nil.blue` — `NoMethodError` at render time. Member-chain roots
+    that resolve to a known-local binding now fall through to the
+    snake_case bare reference with an unresolved marker rather than the
+    `nil` placeholder.
+  - `["a", "b"].map((x) => <li/>)` lost the array literal and emitted
+    `[].each` because the translator can't parse `[...]`. The lowering
+    now recognizes ArrayExpression iterables and routes them through
+    the recursive ArrayLiteral path.
+
+### Spec count
+
+- Up to 343 examples (from 304), all green. `bundle exec rubocop` clean.
+
 ## [0.3.0] - 2026-05-10
 
 Driven by a 929-file stress run against the entire `reserv-web` codebase

data/README.md

@@ -13,7 +13,7 @@ gem itself emits.
 
 ```
 JSX text ──► Babel AST ──► Ruby AST ──► IR ──► backend ──► .rb / .html.erb / _controller.js
-            (Node sidecar) (typed tree) (sema)        (ViewComponent / RailsView / RoutesScript)
+            (Node sidecar) (typed tree) (sema)        (ViewComponent / RailsView / Phlex / RoutesScript)
 ```
 
 ## Installation
@@ -40,6 +40,17 @@ jsx_rosetta translate path/to/Button.tsx -o app/components
 #     app/components/button_component/button_component.html.erb
 #     app/components/button_component/button_controller.js   (when inline arrow handlers)
 
+# Translate as a single-file Phlex 2.x view class (no separate ERB)
+jsx_rosetta translate path/to/Button.tsx --as=phlex -o app/components
+# →   app/components/button.rb
+#     app/components/button_controller.js     (when inline arrow handlers)
+# With suffix:
+jsx_rosetta translate path/to/Button.tsx --as=phlex --phlex-suffix=Component -o app/components
+# →   app/components/button_component.rb       (class ButtonComponent)
+# With namespace:
+jsx_rosetta translate path/to/Button.tsx --as=phlex --phlex-namespace=Components -o app/components
+# →   app/components/button.rb                 (class Components::Button)
+
 # Translate a route-tied page as a Rails view template (no Ruby class)
 jsx_rosetta translate path/to/Home.tsx --as=view -o app/views/home
 # →   app/views/home/home.html.erb       (rename to index.html.erb)
@@ -96,12 +107,17 @@ JsxRosetta::Backend::RoutesScript.new(source_path: "router.tsx").emit(route_tree
 ```
 
 Optional kwargs to `JsxRosetta.translate`:
-- `backend: :view_component | :rails_view` (default `:view_component`)
-- `helpers: nil | Hash | false` — JSX-name → Rails-helper mapping (see below)
-- `layout: :sidecar | :flat` (default `:sidecar`, ignored for `:rails_view`)
+- `backend: :view_component | :rails_view | :phlex` (default `:view_component`)
+- `backend_options: Hash` — per-backend options (see below)
+- `helpers: nil | Hash | false` — JSX-name → Rails-helper mapping (see below; ViewComponent/RailsView only)
+- `layout: :sidecar | :flat` (default `:sidecar`; ViewComponent only)
 - `typescript: true` — force the TypeScript Babel plugin
 - `source_filename:` — surfaces in parse errors
 
+Phlex backend options (pass via `backend_options:`):
+- `suffix: "Component"` — append a suffix to the class name and file name. Mutually exclusive with `namespace:`.
+- `namespace: "Components"` — wrap the class in a `module Namespace` block. Mutually exclusive with `suffix:`.
+
 ## What translates
 
 | JSX construct                        | Translation                                                |
@@ -159,13 +175,13 @@ auto-perform. Common cases:
   recreate React's runtime in Ruby.
 - React Router's data-router form (`createBrowserRouter([...])`). Only the
   declarative `<Routes><Route>` shape is parsed today.
-- Backends other than ViewComponent and RailsView (Phlex, Slim, LiveView).
+- Backends other than ViewComponent, RailsView, and Phlex (Slim, LiveView).
 - Suspense → Turbo Frame mapping (depends on a data-fetching translation
   story we don't have yet).
 
-## ViewComponent emission targets
+## Emission targets
 
-Two backends, picked via `--as` on the CLI or `backend:` in the API:
+Three backends, picked via `--as` on the CLI or `backend:` in the API:
 
 **`:view_component` (default)** — emits a sidecar layout matching
 ViewComponent's `--sidecar` generator convention:
@@ -185,6 +201,52 @@ Pass `layout: :flat` to revert to the older flat layout
 no Ruby class and no sidecar. Place at `app/views/<controller>/<action>.html.erb`;
 the controller's instance variables become the template's `@x` references.
 
+**`:phlex`** — emits a single-file [Phlex 2.x](https://www.phlex.fun/) view
+class. The JSX template lives inside `view_template` as Ruby method calls,
+not in a separate ERB file:
+
+```ruby
+# app/components/card.rb (default mode)
+# app/components/card_component.rb (suffix: "Component")
+class Card < Phlex::HTML
+  def initialize(title: nil)
+    @title = title
+  end
+
+  def view_template
+    div(class: "card") do
+      h2 { plain @title }
+      yield
+    end
+  end
+end
+```
+
+Three mutually exclusive naming strategies (configurable):
+- **default** — `class FlashyHeader < Phlex::HTML` (collision-prone in large
+  apps where names like `Card` / `User` / `Image` overlap with models).
+- **`suffix: "Component"`** — `class FlashyHeaderComponent < Phlex::HTML`,
+  matches the ViewComponent layout, safest for migrations.
+- **`namespace: "Components"`** — wraps the class in a `module Components`
+  block. Cross-references inside the namespace stay bare (`render Card.new`)
+  and resolve via Ruby's constant lookup.
+
+Stimulus handlers still emit a sibling `_controller.js` skeleton alongside
+the `.rb` — the `data-controller`/`data-action` attrs go inline on the
+element (emitted as `data_controller:`/`data_action:` kwargs; Phlex
+auto-hyphenates underscores at render time), the handler body goes into
+the JS skeleton as a TODO comment.
+
+Attribute emission specifics:
+- Hyphenated JSX attrs (`data-testid`, `aria-label`) emit as snake_case
+  kwargs (`data_testid:`, `aria_label:`). Phlex 2.x converts the
+  underscores back to hyphens on render.
+- camelCase JSX attrs (`viewBox`, `preserveAspectRatio`) preserve
+  verbatim — Phlex only converts underscores, so SVG attributes stay
+  intact.
+- Attributes with characters that aren't valid Ruby identifiers (e.g.
+  `xml:lang`) fall back to a quoted string key inside `**{ "xml:lang" => x }`.
+
 ## Helper mappings
 
 Capitalized JSX tags that have a direct Rails helper analog skip the

data/ROADMAP.md

@@ -0,0 +1,92 @@
+# Roadmap
+
+Forward-looking list of work items. Shipped releases are documented in
+[CHANGELOG.md](CHANGELOG.md); the v0.1.0 design lives in [PLAN.md](PLAN.md).
+
+Items are tagged by source so the lineage is traceable:
+- **[review]** — surfaced by a subagent sample review of the Phlex
+  stress run (highest signal — these are gaps seen in the wild).
+- **[plan-oos]** — explicitly listed as out-of-scope in a prior release plan.
+- **[stress]** — surfaced by the 929-file stress run rejection logs.
+
+## Next up
+
+v0.5.0 ships every roadmap "Larger features" item that was queued. The
+remaining work in this file is Stress-test residual triage and Polish.
+
+## v0.5+ — Larger features
+
+_All previously-listed items shipped in v0.5.0. Drop new larger
+features here as they surface._
+
+## Stress-test residuals (42/929 rejected)
+
+The non-component-shape rejections each have a classifier-tagged error
+message; most are intentional drops. Worth revisiting if a specific
+shape becomes high-value:
+
+- [ ] Custom-hooks modules (`useFoo.ts` returning behavior) —
+  classifier says "translate behavior to Stimulus." [stress]
+- [ ] Side-effect-only modules — classifier says "register in a Rails
+  initializer." [stress]
+- [ ] Types-only / constants-only modules — currently dropped; could
+  emit Ruby constants for the constants subset. [stress]
+- [ ] Mixed-export modules — classifier asks the human to split the
+  file. No automated fix planned. [stress]
+
+## Polish / quality
+
+- [ ] **Spec coverage gap.** Some v0.4.0 fixes (template-literal
+  escaping, multi-line comment prefixing) have one spec each; consider
+  fuzzing across a broader corpus.
+- [ ] **README update.** v0.3.0 added the Phlex backend, v0.4.0 closed
+  many gaps — README still describes the v0.2.0 ViewComponent-only
+  surface. Add a Phlex section and an example of the recursive
+  object-literal translation.
+- [ ] **CHANGELOG TLDR.** The v0.4.0 entry is dense; a one-paragraph
+  "what this means for users" intro would help.
+
+## Done — historical reference
+
+See [CHANGELOG.md](CHANGELOG.md). Major arcs to date:
+- **v0.1.0** — ViewComponent backend, three-stage pipeline.
+- **v0.2.0** — Stimulus extraction, sidecar layout, helpers, RailsView,
+  routes, compound components, asChild polymorphism, React hooks.
+- **v0.3.0** — Phlex 2.x backend (three naming strategies), 887/929
+  clean translations.
+- **v0.4.0** — Closed nine gaps surfaced by a sample review of v0.3.0
+  Phlex output (A, B, D, E, F, G, H, J, K); 0/1224 syntax failures
+  (down from 25); 343 specs.
+- **v0.5.0** — Closed all four v0.5.0 candidate items from the v0.4.0
+  sample review **plus** every "Larger features" item that was queued:
+  - useCallback / useRef / useMemo identifier-bound hook results captured
+    in `local_binding_names` so use sites emit `nil` instead of bare
+    snake_case refs to nonexistent methods.
+  - `BinaryExpression` / `LogicalExpression` translation in the
+    `ExpressionTranslator` (incl. `===`/`!==`/`??` mapping).
+  - Optional chaining (`?.`) → safe navigation (`&.`) in member chains.
+  - Nested render-function locals (`const renderHeader = () => <div/>;
+    ... {renderHeader()}`) extracted to private methods on the class.
+  - `error && <X/>` guard on a known local no longer collapses to
+    `if nil` — falls through to the TODO path.
+  - Apollo hooks (`useQuery` / `useLazyQuery` / `useMutation` /
+    `useSubscription` / `useApolloClient`) detected with the GraphQL
+    operation name extracted from a bare-Identifier first argument;
+    emitted as a dedicated TODO block pointing at the Rails controller
+    fetch. Stress-test impact: 221/929 files now carry the Apollo block
+    (281 operation names captured).
+  - Next.js navigation hooks (`useRouter` / `usePathname` /
+    `useSearchParams` / `useParams` / `useSelectedLayoutSegment(s)`)
+    detected and surfaced in a dedicated TODO block listing each
+    hook's Rails analog. Stress-test impact: 105/929 files now carry
+    the Next.js block.
+  - Class-component support (`render()` method extraction, `this.props.X`
+    → `@x` translation, non-render members captured as TODO comments).
+    The 4 class-component residuals now translate cleanly.
+  - Data-factory components (`export const createColumns = (token) =>
+    [{...}]`) lower with `mode: :data_factory`; Phlex emits a snake_case
+    method that returns the translated array, with JSX render lambdas
+    extracted to private methods.
+  - Pretty-printing for long `ObjectLiteral` / `ArrayLiteral` output:
+    multi-line layout when single-line exceeds 80 chars; short literals
+    stay inline.

data/lib/jsx_rosetta/ast/inflector.rb

@@ -19,6 +19,21 @@ module JsxRosetta
         parts = string.split("_")
         parts[0] + parts[1..].map(&:capitalize).join
       end
+
+      # Emit a Ruby string literal in the rubocop-default single-quoted
+      # form when safe. Falls back to `String#inspect` (double-quoted with
+      # escapes) when the source contains characters that prevent the
+      # single-quoted form: single quotes themselves, backslashes (Ruby
+      # single-quoted strings only escape `\\` and `\'`), or control
+      # characters (`\n`, `\t`, etc — single-quoted strings render those
+      # literally). Non-ASCII characters (emojis, unicode) are fine in
+      # single-quoted strings, so they don't force the fallback.
+      def ruby_string_literal(value)
+        str = value.to_s
+        return str.inspect if str.include?("'") || str.include?("\\") || str.match?(/[\x00-\x1f\x7f]/)
+
+        "'#{str}'"
+      end
     end
   end
 end

data/lib/jsx_rosetta/ast/node.rb

@@ -66,7 +66,10 @@ module JsxRosetta
       end
 
       # Field access. Accepts snake_case symbols/strings (translated to
-      # camelCase) and camelCase strings (used verbatim).
+      # camelCase) and camelCase strings (used verbatim). Returns whatever
+      # the raw hash contains at that key (Node, Array of Nodes, String,
+      # Hash, nil) — caller is responsible for type-checking. For typed
+      # access, prefer `#child` (returns Node | nil).
       def [](key)
         raw_key = key.to_s
         return Node.wrap(@raw[raw_key]) if @raw.key?(raw_key)
@@ -75,6 +78,30 @@ module JsxRosetta
         Node.wrap(@raw[camel_key])
       end
 
+      # Typed child access — returns the wrapped Node at `key`, or nil if
+      # absent or non-Node-shaped. Use this in lowering passes to avoid
+      # repetitive `is_a?(AST::Node)` defenses.
+      def child(key)
+        value = self[key]
+        value.is_a?(Node) ? value : nil
+      end
+
+      # Type predicate on a known Node. Use only when the receiver is
+      # guaranteed to be a Node — otherwise prefer `Node.matches?` (class
+      # method) which tolerates nil / non-Node values from hash lookups.
+      # Accepts multiple types: `node.of_type?("StringLiteral", "NumericLiteral")`.
+      def of_type?(*types)
+        types.include?(type)
+      end
+
+      # Defensive type predicate. True iff `value` is an AST::Node whose
+      # type is one of `types`. False for nil, arrays, strings, hashes, or
+      # any non-Node — making it safe for raw hash field accesses where
+      # the contents may be anything.
+      def self.matches?(value, *types)
+        value.is_a?(Node) && types.include?(value.type)
+      end
+
       def dig(*keys)
         keys.reduce(self) do |current, key|
           break nil if current.nil?