jsx_rosetta 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7b64119bbfe86413da7a779ada7e47cab06088411cb4667be2e79f8cfba3464
-  data.tar.gz: c1c1ac742642015a6ae7037538a34bf58b42b6e2fc232bedf48f8660b13a640d
+  metadata.gz: 229956b183e3760f9555874fef214d7ce66d549a603e9d431f5c28251db25bb4
+  data.tar.gz: 226c173f5e1010d154801740a2924bbc776ff8eede26587ec1d9d796da51c5f1
 SHA512:
-  metadata.gz: 44a3dc2fc89b0dbb59ca5026f2cb27cc7f22e498cf125483725e1db07a39db1e45616baff9766be82bc52e443b33bf64180b90175660536c91f4bfc89e5b1926
-  data.tar.gz: a9c999e35af23ff2aba38a02ff57fc6229bf051dc339db859c341c9c1d607f88278542abd07a742ac84840616a305dcfe48b8bad32767ffbf5fc8d08c45ef7a9
+  metadata.gz: 4dbf8ac15094f2462a38c65dfbf539163cfb471077e4bd8874893eda3262da031df72da161793f4c65d75597d55c1d7ea09b395f991fb7fcf80b074d6a74e7ca
+  data.tar.gz: 94627c0471abeab22e92727047ec9e870439297bc6df6447da1bfb79914415d14abc665d3b2325d9496615e62c3f0099898db11a6c05dfd37acf739aa0af518c

data/CHANGELOG.md

@@ -1,6 +1,220 @@
 # Changelog
 
-## [Unreleased]
+## [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
 

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