jsx_rosetta 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b64119bbfe86413da7a779ada7e47cab06088411cb4667be2e79f8cfba3464
-  data.tar.gz: c1c1ac742642015a6ae7037538a34bf58b42b6e2fc232bedf48f8660b13a640d
+  metadata.gz: 161aa59c1e226755b166b5c7366d0c2b5bc1b3d1f55762b1c8c37f551392179a
+  data.tar.gz: 826dd0aff4042b710b354b79c0aa912587477c0f7b07892541fa0e1c7bed090b
 SHA512:
-  metadata.gz: 44a3dc2fc89b0dbb59ca5026f2cb27cc7f22e498cf125483725e1db07a39db1e45616baff9766be82bc52e443b33bf64180b90175660536c91f4bfc89e5b1926
-  data.tar.gz: a9c999e35af23ff2aba38a02ff57fc6229bf051dc339db859c341c9c1d607f88278542abd07a742ac84840616a305dcfe48b8bad32767ffbf5fc8d08c45ef7a9
+  metadata.gz: ea022328a7f0cc56e87b08064a2aa4cb602254caf66c5f0f511faa295f8823867ba1fcfece9952d8d1fb064993736af21df8d060ef3b20ddd0ff8788d8f65d8c
+  data.tar.gz: fa4085f3972ec65ba2062bbed47f936fb0519d37220d6631fd8c427d03edfb2e20ecf3961fc9dd650f6b27d82db43bd2196a3d9e7b3ab44284d06a07b608efac

data/CHANGELOG.md

@@ -2,6 +2,344 @@
 
 ## [Unreleased]
 
+### Added — translate cva() variant builders into Ruby constants
+
+- **`const fooVariants = cva(base, { variants, defaultVariants })`** —
+  the dominant variant-builder pattern in shadcn/ui-shaped components —
+  used to land as a 40-line TODO comment block above the class, and
+  its use-site `cn(fooVariants({ variant }), className)` emitted the
+  verbatim JS as a literal string into the `class:` attribute. Both
+  paths are now translated end-to-end.
+  - Lowering recognizes the `cva(<base>, { variants, defaultVariants,
+    compoundVariants })` call shape and records it as a new
+    `IR::CvaBinding` node (parallel to `IR::LocalBinding`).
+  - Phlex backend renders each `CvaBinding` as three module-level
+    Ruby constants alongside the class — `FOO_BASE_CLASS`,
+    `FOO_VARIANT_CLASSES` (a frozen hash of axis → option → class
+    string), and `FOO_DEFAULT_VARIANTS`.
+  - The use-site call `cn(fooVariants({ variant, size }), className)`
+    in a `className={...}` attribute now emits a Ruby string
+    interpolation against those constants:
+    `"#{FOO_BASE_CLASS} #{FOO_VARIANT_CLASSES["variant"][@variant]}
+    #{FOO_VARIANT_CLASSES["size"][@size]} #{@class_name}"`.
+  - `render_initializer` now uses `defaultVariants` as the Ruby kwarg
+    default for any prop name matching a cva axis (so `variant:
+    "default"` flows from the cva binding even though the React
+    function signature took the prop undefaulted).
+- `compoundVariants` (the rule-of-rules cva feature) is not yet
+  translated — the verbatim JS source surfaces as a `# TODO:
+  compoundVariants from FOO aren't translated` comment alongside the
+  emitted constants so the reviewer can hand-port the rules.
+- Other module-level constants (non-cva) still take the existing
+  "# TODO: module-level constants" pre-class comment path.
+
+### Added — drop Slot.Root branch from polymorphic asChild tags
+
+- **shadcn's `<Comp asChild>` no longer NameErrors at render.** Components
+  using `const Comp = asChild ? Slot : "div"` (or `Slot.Root`) routed
+  the truthy branch through Radix's `Slot`, which has no Ruby class on
+  the Phlex side. Lowering now detects this Slot-vs-tag conditional
+  (Slot rooted at a `radix-ui`/`@radix-ui/react-*` import) and emits
+  only the non-Slot branch — no conditional, no `as_child` kwarg,
+  just the underlying tag.
+- New CLI flag `--keep-slot` and `JsxRosetta.translate(..., keep_slot:
+  true)` preserves the full polymorphic conditional for consumers
+  that shim `Components::Slot::Root` themselves.
+- Detection respects the import source: a project-local `import
+  { Slot } from "./my-slot"` is untouched.
+
+### Added — map known Radix primitive tags to underlying HTML elements
+
+- **`<SeparatorPrimitive.Root />`, `<LabelPrimitive.Root />`, etc.**
+  used to lower as `ComponentInvocation`s, producing
+  `render SeparatorPrimitive::Root.new(...)` — undefined constants,
+  NameError on render. Now: when the import source matches a Radix
+  package (`radix-ui`, `@radix-ui/react-*`) and the
+  `(LocalName, Member)` pair is in a small registry, lower as an
+  HTML Element with the underlying tag and any always-applied
+  attributes (`role`, `type`, etc.). Consumer attrs win on collision
+  with the registry defaults.
+- Registry lives at `lib/jsx_rosetta/ir/radix_registry.rb`. Covers
+  Separator / Label / Avatar (Root/Image/Fallback) / Switch
+  (Root/Thumb) / Progress (Root/Indicator) / AspectRatio (Root) /
+  ScrollArea (Root/Viewport). Unknown primitives fall through to
+  the existing `ComponentInvocation` / TODO behavior.
+- Works with both named-aliased imports
+  (`import { Separator as SeparatorPrimitive } from "radix-ui"`)
+  and namespace imports
+  (`import * as AvatarPrimitive from "@radix-ui/react-avatar"`).
+
+### Added — auto-emit Lucide icon shims as a translation sidecar
+
+- **`import { ChevronRight } from "lucide-react"` now lands a working
+  `ChevronRight` Phlex class.** Previously the translator carried the
+  React import through verbatim, so the generated component contained
+  `render ChevronRight.new(...)` referencing a non-existent Ruby class
+  — NameError at render time. The Phlex backend now detects Lucide
+  imports (`lucide-react`, `lucide`) that are actually used as JSX
+  component tags and emits two kinds of sidecar files:
+  - `lucide_icon.rb` — a shared `LucideIcon < Phlex::HTML` base.
+  - `<icon>.rb` — one file per referenced icon, defining a subclass
+    that renders the vendored SVG path data inline. One file per
+    icon means Zeitwerk autoloads each cleanly under the consumer's
+    `app/components/` (or wherever the output directory points).
+- Vendored path data lives at `lib/jsx_rosetta/icons/lucide.json`
+  (the ~35 icons most commonly imported by shadcn/ui sources). Icons
+  not in the vendored set emit a class whose `inner_svg` is empty
+  with a TODO comment pointing at the lucide.json refresh path.
+- Tolerates both canonical (`ChevronRight`) and legacy `*Icon`
+  (`ChevronRightIcon`) names — same path data either way.
+- `--phlex-namespace=Components` wraps every sidecar in the same
+  module as the main translation, so the consumer's autoloader
+  config doesn't need a special case.
+
+### Added — translate Stimulus controller bodies when safe
+
+- **Paste JSX handler bodies into the generated `_controller.js`.**
+  Auto-generated Stimulus controllers used to leave the handler body
+  as a TODO comment with the verbatim source above an empty
+  `clickHandler(event) { // ... }` stub. For DOM-driven handlers (the
+  common shape in shadcn-style UI), the JSX body is *already valid JS*
+  — we now paste it directly into the method, using the original
+  arrow's parameter name so identifier references in the body still
+  resolve.
+  - `IR::StimulusMethod` gains a `params:` field — the original arrow
+    parameter names — used as the Stimulus method's parameter signature.
+  - New `safe_to_paste_handler?` heuristic on the Phlex backend bails
+    out (falls back to the previous TODO behavior) when the body
+    references React state setters (`setX(`), React hooks (`useX(`),
+    or is just an identifier-bound `// originally bound to: …` comment.
+  - Collision markers are preserved across the new path.
+
+### Fixed — silent children loss on self-closing-with-spread tags
+
+- **Auto-yield on blockless spread-children tags.** The shadcn idiom
+  `<tag {...props} />` (self-closing JSX whose rest-spread carries React
+  `children`) translated to a Phlex `tag(..., **(@props || {}))` call
+  with no block — so callers' `Component.new { ... }` blocks were
+  silently dropped at render. Now: when an Element or
+  ComponentInvocation has no explicit IR children, a `SpreadAttribute`,
+  and a non-void tag, emit `tag(...) do; yield if block_given?; end`.
+  The `block_given?` guard preserves the no-block use case. Void HTML
+  elements (input, img, br, …) still emit blockless. Explicit-children
+  paths and `RenderProp` flows are untouched.
+
+## [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
@@ -94,9 +432,6 @@ generated Ruby parsed but didn't behave like the source JSX.
 
 ### 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
@@ -122,10 +457,8 @@ generated Ruby parsed but didn't behave like the source JSX.
 
 ## [0.3.0] - 2026-05-10
 
-Driven by a 929-file stress run against the entire `reserv-web` codebase
-(`reserv-web/src/` + `reserv-web/pages/` + `packages/`). Baseline outcome
-on v0.2.0: 838/929 (90.2%) clean exit, 91 hard failures across 5 distinct
-error categories. This release ships fixes for all five plus a follow-up
+Baseline outcome on v0.2.0: 838/929 (90.2%) clean exit, 91 hard failures across
+5 distinct error categories. This release ships fixes for all five plus a follow-up
 that opens up lowercase JSX-returning helpers as components, lifting the
 corpus to **887/929 (95.5%) clean exit**. The 42 remaining failures are
 non-component modules (utility/hook libraries, AG-Grid column
@@ -207,10 +540,8 @@ initializers); each now reports a classifier-tagged error that explains
 
 ## [0.2.0] - 2026-05-10
 
-Driven by an empirical probe of v0.1.0 against a 39-file Next.js production
-slice (`reserv-web/src/components/rolloverbook`). The slice exposed three
-return-shape gaps and a crash on nested destructure; this release fixes all
-four. Probe outcome: 33/39 → **39/39 emit**.
+The slice exposed three return-shape gaps and a crash on nested destructure;
+this release fixes all four. Probe outcome: 33/39 → **39/39 emit**.
 
 ### Fixed
 

data/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+The README has the user-facing pipeline overview, backend trade-offs, and CLI surface. This file covers the things that aren't obvious from the README or a cold read of the source.
+
+## Common commands
+
+```bash
+bin/setup                                                # bundle install + npm install in node/ (required after fresh clone)
+bundle exec rspec                                        # full test suite
+bundle exec rspec spec/backend/phlex_spec.rb             # single file
+bundle exec rspec spec/backend/phlex_spec.rb:123         # single example by line
+bundle exec rspec -e "guard-ladder"                      # examples whose describe/it matches
+bundle exec rubocop
+bundle exec rake                                         # default: rspec + rubocop
+bundle exec exe/jsx_rosetta translate path/X.tsx --as=phlex --phlex-suffix=Component -o /tmp
+```
+
+`bin/setup` is the first-run requirement — the Node sidecar's `node_modules` isn't bundled, and `JsxRosetta.parse` shells out to `node/parse.js`. If `rspec` fails with parser errors, re-run `bin/setup`. `JSX_ROSETTA_NODE` overrides the `node` binary path.
+
+`tmp/run_phlex_stress.sh` translates a large external JSX/TSX corpus through the Phlex backend; results land in `tmp/stress/` (gitignored). Use after non-trivial changes to confirm clean-translation count and `ruby -c` pass count don't regress. The TSV at `tmp/stress/phlex_results.tsv` is the headline.
+
+## Pipeline
+
+JSX → Babel AST → IR → backend. See README for the user-facing diagram. Hot files:
+
+- `lib/jsx_rosetta/ir/lowering.rb` (1700+ lines, single class) — the source of truth for AST→IR. New translation behaviors land here.
+- `lib/jsx_rosetta/ir/types.rb` — `Data.define`'d value classes. `IR::Component` is the root.
+- `lib/jsx_rosetta/backend/view_component/expression_translator.rb` — shared by every backend for JS-expression fragments inside JSX bodies/attributes. Despite the directory name, the Phlex backend uses it too.
+- `lib/jsx_rosetta/backend/phlex.rb` — the most actively maintained backend; most recent improvements target it first.
+
+When in doubt, lowering preserves verbatim JS as `IR::Interpolation` so the backend's `ExpressionTranslator` can take a second pass at it.
+
+## ExpressionTranslator identifier resolution (load-bearing)
+
+An identifier reference inside JSX is classified into one of five buckets in order. This is the central machinery for closing render-time NameErrors — most recent fixes work by tightening which names land in bucket 4.
+
+1. **Local scope** (pushed via `with_locals` — loop bindings, render-prop params, render-method params) → bare snake_case.
+2. **Prop alias** (`"data-testid": dataTestId` in destructure) → `@ivar` of the underlying prop name.
+3. **Prop name** → `@snake_case_ivar`.
+4. **`local_binding_names` ∪ `imported_names`** (hook tuple destructures, top-level `const`/`function`/`import` declarations) → `nil` at leaf position; **bail** (return nil from the translate call) at member-chain root / unary operand / binary operand. The bail routes the caller into a TODO emission instead of a bare snake_case ref that NameErrors at render.
+5. **Fallthrough** → bare snake_case identifier, recorded as `unresolved`. Backends drop with TODO on uppercase (PascalCase / SCREAMING) since those are almost always imports; lowercase passes through as a Rails-helper-shaped reference (`current_user` etc).
+
+When adding a "we know X exists but can't translate it" class, plumb the names into the translator via `imported_names:` or `local_binding_names:` so bucket 4 fires.
+
+## Project conventions
+
+- **Preserve-as-TODO over speculative translation.** Flag `# TODO:` with verbatim source rather than guess. Translator bailout + backend drop-with-TODO helpers exist to keep this safe.
+- **No JS-to-Ruby translation paths that best-guess arbitrary call expressions.** Extending the `ExpressionTranslator` for unambiguous mappings (`===`→`==`, `??`→`||`, etc.) is fine; guessing call semantics is not.
+- **No external-corpus references in committed artifacts.** Specs, fixtures, source comments, commit messages, CHANGELOG, README must stay generic ("the stress corpus" / "a real-world JSX corpus"). Anything under `tmp/` is gitignored and can reference whatever.
+
+## Emission rules that are subtle
+
+- **Phlex attribute casing.** HTML-element attrs (lowercase tag) preserve camelCase verbatim — Phlex 2 only converts `_` to `-`, so SVG attrs like `preserveAspectRatio` and `viewBox` must stay camelCase. Component invocations (PascalCase tag) full-snake_case all keys per Ruby kwarg convention. See `plain_attribute_part` in `backend/phlex.rb`.
+- **Dropped attributes are omitted, not nilled.** When a value bails to `nil` with a recorded TODO, the entire kwarg drops from the emission (the TODO above the element is the record). Explicit `attr={null}` in source still emits `attr: nil` (translation succeeded, no TODO → not a drop). Mechanism: `plain_attribute_part` watches whether a TODO was appended during value computation.
+- **Sibling components share `module_bindings` by reference.** `lower_all` attaches the *same* array to every sibling, so backends emit the constants TODO prefix only on the first sibling via `first_emit_for_module_bindings?` (object-identity check on the array).
+- **JSX in non-child positions** lowers through `lower_value_expression` → `lower_jsx_value`. Single-child Fragments unwrap (common React workaround for "single ReactNode required"). Hit by attribute values (`icon={<Foo/>}`) and render lambdas in column-config arrays.
+- **Inline arrow handlers split by tag case.** On PascalCase tags, lower to `IR::EventHandler` (verbatim JS body) → backend extracts a stub instance method (`handle_click`, `handle_change`) and emits `on_click: method(:handle_click)`. On HTML elements, lower to Stimulus method extraction instead (see `stimulus_methods` on `IR::Component`).
+
+## Spec gotchas
+
+- `spec/backend/phlex_spec.rb` is the canonical large suite (~1000 lines now) — most behavior changes get their regression cover here.
+- The Phlex spec helper's `files_for` uses **no suffix by default** — paths are `x.rb` (not `x_component.rb`) unless the spec passes `suffix: "Component"`.
+- `spec/fixtures/jsx/*.{jsx,tsx}` + `spec/fixtures/expected/*` feed the Button full-IR-equality test; touch carefully.
+- `spec/.rspec_status` is gitignored and huge — don't read it.
+
+## Commit message style
+
+Recent commits use a focused subject + structured body (subject explains *what changed*, body has sections like "Bug fixes:", "Implementation:", "Stress corpus impact:"). When behavior changes shift the stress numbers (clean translations / syntax fails / top dropped-attribute categories), include before/after counts in the body — they're the most useful signal for whether the change earns its complexity.

data/README.md

@@ -168,6 +168,56 @@ auto-perform. Common cases:
 - **Reserved Rails controller names** (in the routes script) → `# WARNING:`
   line listing collisions.
 
+## Resolving TODOs (optional Claude Code skill)
+
+The repository ships an optional [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) skill and worker agent that automate the last-mile work of clearing `# TODO:` comments from the generated output. The skill is fully generic — it ships no app-specific assumptions, no design-system data, and no host-stack conventions. You bring those.
+
+**What it does:**
+
+- A pure-Ruby corpus scanner (`tools/discover_bailouts.rb`) tallies the dropped-expression patterns in your generated output and surfaces likely design-system / config-namespace clusters.
+- A pure-Ruby substitution pass (`tools/apply_substitutions.rb`) reads a YAML you supply (`match:` regex + `tokens:` value table) and splices values into the generated `render Foo.new(...)` calls. Always validates with `ruby -c` before writing; reverts on failure.
+- LLM-driven recipes for React hooks, Apollo data fetching, event handlers, Next.js navigation, and module-level constants. These default to **sharpening** verbose TODOs into single-decision items rather than guessing translations.
+- A `jsx-rosetta-resolve-todo-file` worker agent for parallel fan-out across a corpus.
+
+A reference Ant Design v5 token mapping ships under `examples/` — drop-in usable if your source app uses Ant Design with default theming.
+
+**Layout in this repo:**
+
+```
+skills/jsx-rosetta-resolve-todos/
+├── SKILL.md                     # workflow + routing table
+├── recipes/                     # per-TODO-class recipes
+├── tools/                       # discover_bailouts.rb, apply_substitutions.rb
+├── data/design_tokens.template.yml   # blank schema for your design system
+└── examples/design_tokens.ant_design_v5.yml   # reference for Ant-using apps
+
+agents/
+└── jsx-rosetta-resolve-todo-file.md   # fan-out worker definition
+```
+
+**Installing into your environment:**
+
+User-level (available in every Claude Code session on your machine):
+
+```bash
+mkdir -p ~/.claude/skills ~/.claude/agents
+ln -s "$(pwd)/skills/jsx-rosetta-resolve-todos" ~/.claude/skills/
+ln -s "$(pwd)/agents/jsx-rosetta-resolve-todo-file.md" ~/.claude/agents/
+```
+
+Project-level (only available in the consuming Rails app):
+
+```bash
+# from your Rails app's repo root
+mkdir -p .claude/skills .claude/agents
+cp -R /path/to/jsx_rosetta/skills/jsx-rosetta-resolve-todos .claude/skills/
+cp /path/to/jsx_rosetta/agents/jsx-rosetta-resolve-todo-file.md .claude/agents/
+```
+
+In either case, your app-specific configuration (the populated `data/design_tokens.yml`, `data/target_app_conventions.md`, etc.) belongs **inside the consuming app's** `.claude/skills/jsx-rosetta-resolve-todos/data/` — not here. Anything app-specific should be `.gitignore`d in your Rails repo if it shouldn't be shared.
+
+The scripts under `tools/` are runnable directly with `ruby` — Claude Code is not required to use them. The recipes and the agent are what require Claude Code.
+
 ## What's deferred
 
 - Translating React state primitives (`useState` / `useEffect` etc.). 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.