jsx_rosetta 0.5.1 → 0.6.0

data/skills/jsx-rosetta-resolve-todos/recipes/01_design_tokens.md

@@ -0,0 +1,74 @@
+# Recipe 01 — Design tokens
+
+## Shape
+
+```
+# TODO: (attribute|style declaration) "<name>" dropped — couldn't translate: <RHS>
+<render Foo.new(...)>
+```
+
+…where `<RHS>` matches a token-system regex you've configured (e.g. `token\.(\w+)` for Ant Design, `theme\.palette\.(\w+)\.main` for MUI, `vars\.colors\.(\w+)` for vanilla-extract).
+
+## Status
+
+**Backed by `tools/apply_substitutions.rb`** — pure-Ruby mechanical pass, no LLM.
+
+## Action
+
+**Resolve** via `tools/apply_substitutions.rb`. This is a pure-Ruby pass — no LLM call, no agent dispatch.
+
+```bash
+ruby tools/apply_substitutions.rb \
+  --config data/design_tokens.yml \
+  <generated_components_dir>
+```
+
+Run this **before** any LLM-driven recipe so the corpus is smaller and cheaper to fan out over.
+
+## How the substitution works
+
+For each matched TODO, the script:
+
+1. Looks up the captured key in the YAML's `tokens:` map.
+2. Skips if the entry is missing or has `value: null` (explicitly opted out).
+3. Locates the next single-line `render <Component>.new(...)` below the TODO.
+4. Splices:
+   - **style declaration** → into the existing string-literal `style:` (or creates a new `style:` kwarg)
+   - **attribute** → as a snake_cased kwarg
+5. Writes only if `ruby -c` passes on the result; otherwise reverts.
+
+## When to skip / sharpen instead
+
+The script handles the easy 60–75% of token TODOs. The cases it leaves untouched (and which a downstream recipe should sharpen, not blindly resolve):
+
+- **Multi-line render calls.** When the render's argument list spans physical lines or uses hash-form `style: { ... }`, the script bails. Sharpening these requires Ruby-aware editing.
+- **Template literals as RHS.** `` `${token.paddingSM}px ${token.padding}px` `` — multiple token refs woven into a string. Resolving this needs RHS evaluation, which the v1 script doesn't do.
+- **Conditionals as RHS.** `!thumbnailUrl ? token.colorFillQuaternary : undefined` — the resolved color is conditional on runtime state, not a constant.
+- **Component-namespace tokens.** `token.Tag.colorText`, `token.Layout.headerBg` — these depend on the consuming app's `ConfigProvider` overrides and have no safe default.
+
+For each, sharpen to a TODO of the form:
+
+```ruby
+# TODO[design_token]: <attr> = <verbatim RHS>. Resolve to your <design system> theme value.
+```
+
+## Building the YAML for your design system
+
+If your source codebase uses a known design system with default theming, check `examples/` first — it may already have a ready-made YAML you can use as-is.
+
+Otherwise:
+
+1. Run `tools/discover_bailouts.rb` on the generated corpus.
+2. Identify the dominant root in the "Repeating member chains" section.
+3. Copy `data/design_tokens.template.yml` to `data/design_tokens.yml`.
+4. Paste the suggested `match:` regex.
+5. For each top key, look up the design system's published default (or your theme override) and add an entry.
+6. Run `apply_substitutions.rb --dry-run` to preview.
+7. Drop `--dry-run` to commit the edits.
+8. Re-run `discover_bailouts.rb` to confirm the count dropped.
+
+## Anti-patterns
+
+- **Don't** populate the YAML from training-data guesses about a design system you haven't verified. Token names and defaults change across versions; check the source codebase or the system's docs.
+- **Don't** ship overrides specific to one consuming app in this skill's `data/` directory. App-specific overrides belong in the consuming repo's `.claude/skills/jsx-rosetta-resolve-todos/data/` (gitignored or scoped to that repo).
+- **Don't** auto-resolve when the script reports `parse_failed` — investigate the input. The post-edit revert is a safety net, not a normal-path outcome.

data/skills/jsx-rosetta-resolve-todos/recipes/02_promoted_ivar.md

@@ -0,0 +1,49 @@
+# Recipe 02 — Promoted-to-@ivar reminders
+
+## Shape
+
+```
+# TODO: render condition references binding(s) promoted to @ivar — thread as controller-passed prop(s): <name1>, <name2>, ...
+<valid Ruby that uses @<name1>, @<name2>>
+```
+
+## Status
+
+**Backed by `tools/apply_promoted_ivar.rb`** — pure-Ruby mechanical pass, no LLM.
+
+## Action
+
+**Resolve / sharpen** via `tools/apply_promoted_ivar.rb`. Pure-Ruby, no LLM.
+
+```bash
+ruby tools/apply_promoted_ivar.rb [--dry-run] [--quiet] <file_or_dir>...
+```
+
+The script:
+
+1. Parses each TODO's named prop list.
+2. Reads the file's first `def initialize(...)` signature and extracts kwarg names.
+3. Classifies each name:
+   - **camelCase prop** present in `initialize` (after snake_casing) → satisfied
+   - **camelCase prop** missing from `initialize` → flag as missing
+   - **PascalCase identifier** → flag as external constant needing import/removal (these are class/enum references that `jsx_rosetta` couldn't resolve, not props you'd thread from a controller)
+4. If every name is satisfied → **delete** the TODO entirely.
+5. If anything is missing → **sharpen** to a tagged single-liner naming exactly what's missing:
+   ```ruby
+   # TODO[promoted_ivar]: controller must pass <missing_props> (not in def initialize); external constant(s) <PascalNames> need import or removal.
+   ```
+
+Always validates with `ruby -c` before writing; reverts on parse failure.
+
+## Why this is mechanical
+
+The Ruby below the TODO is already valid and correct. The reason `jsx_rosetta` emits it: when a JSX render condition refers to a name that was a top-level `const` or `import` in the source, it gets promoted to a `@<name>` ivar in Phlex output. The TODO reminds the author to thread that name from the controller. If the author already added it to `initialize`, the reminder is satisfied.
+
+## Expected resolution rate
+
+Depends on conversion stage:
+
+- **Fresh translation, controllers not yet written** → close to 100% sharpen, 0% resolve. Pure compression win — verbose multi-line reminders become tagged single-liners that are grep-friendly and explicitly call out what each TODO needs (props vs imports).
+- **After controllers are wired** → resolve rate climbs as `initialize` signatures gain the named props. Re-running the script becomes idempotent cleanup: each pass deletes any TODO whose props have caught up.
+
+Run this script after `apply_substitutions.rb` and again any time you've updated a controller signature.

data/skills/jsx-rosetta-resolve-todos/recipes/03_react_hooks.md

@@ -0,0 +1,34 @@
+# Recipe 03 — React hooks
+
+## Shape
+
+```
+# TODO: React hooks detected. None translate automatically.
+# Hotwire/Stimulus handles behavior; controllers/views handle state;
+# turbo-frames handle async loading. Original source:
+#   <verbatim hook block>
+```
+
+## Status
+
+**Documented intentions** — recipe describes the recommended LLM-driven action (the sub-classification table below is usable by an agent today); no backing tooling yet. Validation against a real conversion will inform whether parts of this become mechanical.
+
+## Action
+
+**Sharpen** by sub-classifying each hook in the dumped block. Default action per hook:
+
+| Hook | Sharpened TODO template |
+|---|---|
+| `useState` | `# TODO[useState]: ephemeral UI state \`<name>\` (type <T>). Move to Stimulus controller value.` |
+| `useMemo` | `# TODO[useMemo]: derived value \`<name>\`. Derive in controller and pass as @<name>; or extract to a helper if pure.` |
+| `useRef` | `# TODO[useRef]: DOM ref \`<name>\`. Replace with Stimulus target: data-<controller>-target="<name>".` |
+| `useEffect` | `# TODO[useEffect]: side effect. Split into Stimulus connect/disconnect (DOM lifecycle) or Turbo Frame load (async).` |
+| `useCallback` | (drop — no React render model means no value) |
+| Custom `use*` | `# TODO[custom-hook]: \`<name>\` — review and reimplement; no automatic mapping.` |
+
+Preserve the original block as `# Original:` for traceability.
+
+## When to escalate
+
+- Hook with significant computation that would change behavior if naively moved
+- Custom hooks that wrap data fetches, subscriptions, or business logic

data/skills/jsx-rosetta-resolve-todos/recipes/04_apollo_hooks.md

@@ -0,0 +1,34 @@
+# Recipe 04 — Apollo data-fetching hooks
+
+## Shape
+
+```
+# TODO: Apollo data-fetching hooks detected. None translate automatically.
+# <guidance text>
+#   <verbatim useQuery / useMutation block>
+```
+
+## Status
+
+**Documented intentions** — recipe describes the recommended LLM-driven action; no backing tooling yet. The sharpen template + extraction rule below is usable by an agent today, but the GraphQL operation parsing has only been spec'd, not implemented.
+
+## Action
+
+**Sharpen.** Recipe is constant: Apollo fetches → Rails controller fetches → component receives data as a prop.
+
+Extract the GraphQL operation name and variables from the dumped block, then emit:
+
+```ruby
+# TODO[apollo]: controller fetch — <Operation> with vars { <var1>, <var2> }.
+#   In <controller>#<action>, set @<name> = <ResolverClass>.call(<vars>) and
+#   pass to this component as <prop_name>: @<name>.
+# Original:
+#   <verbatim hook>
+```
+
+Look up `target_app_conventions.yml` for the consuming repo's resolver/service path. If absent, mark `<TBD: see target_app_conventions.yml>` rather than guessing.
+
+## When to escalate
+
+- `useMutation` blocks — these typically map to form submits, but the form's HTML structure may need restructuring; sharpen with the operation name and let a human design the form.
+- Optimistic updates / cache writes — these are React-state-of-the-world dependent and don't have a 1:1 Hotwire mapping.

data/skills/jsx-rosetta-resolve-todos/recipes/05_event_handlers.md

@@ -0,0 +1,45 @@
+# Recipe 05 — Event handlers
+
+## Shape
+
+A `handle_*` private method stub with verbatim JS in a TODO:
+
+```ruby
+def handle_click
+  # TODO: translate the original JSX `onClick` handler:
+  #   {
+  #     <verbatim JS body>
+  #   }
+end
+```
+
+## Status
+
+**Documented intentions** — recipe describes the recommended LLM-driven action; no backing tooling yet. The classification table below is usable by an agent today.
+
+## Action
+
+**Sharpen** by classifying the handler's body, then prescribe a target:
+
+| Body shape | Classification | Target |
+|---|---|---|
+| Calls a state setter (`setX(...)`) | behavioral UI state | Stimulus action: `data-action="<event>->controller#<method>"`, body becomes JS in the Stimulus controller |
+| Calls a mutation / fetch | data mutation | Form submit to a Rails action; remove the handler, wire the form's `action=` |
+| Calls `router.push(...)` | navigation | Plain `<a>` or `link_to`; remove the handler |
+| Local computation only, no I/O | behavioral | Stimulus action |
+| Mixed | manual | Escalate with a note |
+
+Sharpened TODO sits on the `handle_*` method stub:
+
+```ruby
+def handle_click
+  # TODO[event_handler:behavioral]: setIsOpen toggle. Convert to Stimulus action
+  #   `data-action="click->dropdown#toggle"`; body moves to dropdown_controller.js.
+  # Original:
+  #   <verbatim JS body>
+end
+```
+
+## Why classification matters
+
+Behavioral handlers translate to Stimulus actions; data-mutation handlers translate to form submits. These are very different Rails-side surfaces — the wrong target buys nothing and may hide a real architectural choice the human needs to make.

data/skills/jsx-rosetta-resolve-todos/recipes/06_module_constants.md

@@ -0,0 +1,29 @@
+# Recipe 06 — Module-level constants
+
+## Shape
+
+```
+# TODO: module-level constants — translate to Ruby constants or move to a Rails initializer:
+#   <verbatim const / function / template-tagged block(s)>
+```
+
+## Status
+
+**Documented intentions** — recipe describes the recommended LLM-driven action; no backing tooling yet. The per-declaration sub-type table below is usable by an agent today.
+
+## Action
+
+**Dispatch by sub-type.** Walk the dumped block and classify each declaration:
+
+| Sub-type | Action |
+|---|---|
+| `const X = gql(...)` | Sharpen: "GraphQL operation — see recipe 04 (Apollo). Move to controller." |
+| `function foo(...) { ... }` (pure) | Sharpen: "Helper — extract to `app/helpers/<name>_helper.rb` (view-scoped) or `app/services/` (app-wide)." |
+| `const X = lazy(() => import(...))` | Sharpen: "Lazy-loaded component — wrap render in a Turbo Frame `src=` instead." |
+| `const X = { ... } as const` (lookup map) | **Resolve**: emit Ruby `X = { ... }.freeze` at top of file. |
+| `const X = "literal"` / `const X = 42` | **Resolve**: emit Ruby constant or local. |
+| Other | Sharpen with verbatim body and "no recipe — review." |
+
+## Why per-declaration
+
+A single `module-level constants` block can contain multiple unrelated things (a gql query AND a lookup table AND a helper function). Splitting per-declaration lets each piece take its proper Rails-shaped destination.

data/skills/jsx-rosetta-resolve-todos/recipes/07_nextjs_navigation.md

@@ -0,0 +1,44 @@
+# Recipe 07 — Next.js navigation hooks
+
+## Shape
+
+```
+# TODO: Next.js navigation hooks detected. None translate automatically.
+# <guidance text>
+#   <verbatim useRouter / usePathname / useSearchParams block>
+```
+
+## Status
+
+**Documented intentions** — recipe describes the recommended LLM-driven action; no backing tooling yet. The sharpen templates below are usable by an agent today.
+
+## Action
+
+**Sharpen** with route extraction.
+
+For `useRouter().push("/path/[id]", ...)`:
+
+```ruby
+# TODO[nextjs:nav]: navigation — replace with Rails url helper.
+#   Source: router.push("/foo/[id]"). Likely target: foo_path(id: <id>).
+#   Confirm in config/routes.rb.
+# Original:
+#   <verbatim>
+```
+
+For `router.query.<key>` reads:
+
+```ruby
+# TODO[nextjs:query]: read of router.query.<key>. In a controller action,
+#   this is params[:<key>]. If this component is rendered from a controller,
+#   thread <key> as a prop.
+# Original:
+#   <verbatim>
+```
+
+For `usePathname()` / `useSearchParams()`: sharpen similarly with `request.path` / `params` mappings.
+
+## When to escalate
+
+- Programmatic navigation tied to async data loading (typically becomes a Turbo Stream response from a controller)
+- Conditional routing that depends on client-side state

data/skills/jsx-rosetta-resolve-todos/recipes/08_generic_js_bailouts.md

@@ -0,0 +1,55 @@
+# Recipe 08 — Generic JS bailouts
+
+## Shape
+
+```
+# TODO: translate JS to Ruby — original:
+#   <verbatim JS expression or block>
+```
+
+…or any "<X> dropped" TODO whose RHS doesn't match a configured token regex.
+
+## Status
+
+**Documented intentions** — recipe describes the recommended LLM-driven action; no tooling yet. Always-sharpen by design (see below).
+
+## Action
+
+**Always sharpen. No resolve whitelist.**
+
+This is the largest, most heterogeneous TODO category and the one most prone to "looks easy" hazards. Earlier drafts of this recipe carried a small whitelist (`String(x) → x.to_s`, `x ?? y → x || y`, etc.); on review every entry had at least one observable-behavior divergence:
+
+| Tempting JS → Ruby | Why it's wrong |
+|---|---|
+| `Number(x)` → `x.to_f` | JS returns `NaN` on bad input; Ruby returns `0.0` |
+| `Boolean(x)` → `!!x` | JS-falsy `0`, `""` are Ruby-truthy |
+| `String(x)` → `x.to_s` | Diverges on `null`/`undefined` |
+| `x ?? y` → `x \|\| y` | `??` is null/undefined-only; `\|\|` checks all falsy |
+| `Array.isArray(x) ? x[0] : x` → `Array(x).first` | Object inputs become `[k,v]` tuples in Ruby |
+
+The gem's hard rule applies here too: **if `jsx_rosetta` bailed, it's not safe**. The gem already attempts every translation that has unambiguous semantics; a generic JS bailout is by definition something it considered unsafe to translate. This recipe inherits that posture.
+
+## Sharpen template
+
+Replace the multi-line dump with:
+
+```ruby
+# TODO[js_bailout]: <one-line description of what the source computes>.
+#   Move to <controller / helper / Stimulus> — needs <what info>.
+# Original:
+#   <verbatim, indented>
+```
+
+If the bailout's intent isn't clear from a single read, just preserve and tag — don't invent a description. A truthful "see Original" is more useful than a guessed summary.
+
+## When to escalate
+
+- Bailouts that touch authentication, authorization, or business invariants
+- Bailouts whose Ruby equivalent would change observable behavior
+- Anything whose JS uses APIs without obvious Ruby/Rails equivalents (`navigator.*`, `window.*`, browser-only globals)
+
+## Anti-patterns
+
+- **Don't** add to the resolve whitelist. If a future class of bailout has genuinely unambiguous semantics, the right home is the gem itself, not this recipe — the gem will then stop emitting the bailout in the first place.
+- **Don't** translate function calls whose Ruby/Rails equivalent isn't in the consuming app. Sharpen instead so the human can introduce the helper deliberately.
+- **Don't** speculate about author intent. The verbatim JS is the most useful artifact when the worker can't classify with confidence.

data/skills/jsx-rosetta-resolve-todos/tools/apply_promoted_ivar.rb

@@ -0,0 +1,189 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# apply_promoted_ivar.rb
+#
+# Mechanical resolution of jsx_rosetta TODOs of the form:
+#   # TODO: render condition references binding(s) promoted to @ivar — thread as controller-passed prop(s): NAME1, NAME2, ...
+#
+# These TODOs are reminders, not defects: the Ruby on the line(s) below
+# them is already valid. They flag "the controller must pass these names
+# as props." If every named prop already appears as a kwarg in the file's
+# `def initialize`, the reminder is satisfied and the TODO can be deleted.
+# Otherwise the script sharpens it to list only the names that are
+# actually missing (or that are PascalCase imports needing different
+# treatment).
+#
+# Always re-parses the post-edit file with `ruby -c`; on failure the file
+# is reverted and reported as `parse_failed`.
+#
+# Usage:
+#   apply_promoted_ivar.rb [--dry-run] [--quiet] <file_or_dir>...
+
+require 'json'
+require 'set'
+require 'tempfile'
+require 'optparse'
+
+TODO_RE = /\A(\s*)# TODO: render condition references binding\(s\) promoted to @ivar — thread as controller-passed prop\(s\): (.+?)\s*\z/.freeze
+
+# --- helpers ----------------------------------------------------------------
+
+def camel_to_snake(s)
+  s.gsub(/([a-z0-9])([A-Z])/) { "#{$1}_#{$2}" }.downcase
+end
+
+def pascal_case?(name) = /\A[A-Z]/.match?(name)
+
+# Extract the kwarg names from the first `def initialize(...)` in src.
+# Returns a Set of snake_case names. Returns an empty set if there's no
+# initializer or if its arg list can't be parsed.
+def initialize_kwargs(src)
+  m = src.match(/def initialize\s*\(/m)
+  return Set.new unless m
+
+  start = m.end(0)
+  depth = 1
+  i = start
+  while i < src.length && depth > 0
+    case src[i]
+    when '(' then depth += 1
+    when ')' then depth -= 1
+    end
+    i += 1
+  end
+  return Set.new unless depth == 0
+
+  args_str = src[start...(i - 1)]
+  parse_kwarg_names(args_str).to_set
+end
+
+# Given an arg string like "status: nil, options: { a: 1 }, on_change: nil",
+# return the kwarg names (top-level only — ignores nested-hash keys).
+def parse_kwarg_names(s)
+  names = []
+  depth = 0
+  buf = +''
+  s.each_char do |c|
+    case c
+    when '(', '[', '{' then depth += 1; buf << c
+    when ')', ']', '}' then depth -= 1; buf << c
+    when ','
+      if depth.zero?
+        names << kwarg_head(buf)
+        buf = +''
+      else
+        buf << c
+      end
+    else
+      buf << c
+    end
+  end
+  names << kwarg_head(buf) unless buf.strip.empty?
+  names.compact
+end
+
+def kwarg_head(s)
+  m = s.match(/\A\s*([a-z_][a-z0-9_]*)\s*:/)
+  m && m[1]
+end
+
+# --- file processing --------------------------------------------------------
+
+def process_file(path)
+  src = File.read(path)
+  init_set = initialize_kwargs(src)
+
+  out = []
+  resolved = 0
+  sharpened = 0
+
+  src.lines.each do |line|
+    if (m = TODO_RE.match(line))
+      indent = m[1]
+      raw_names = m[2].split(',').map(&:strip).reject(&:empty?)
+
+      missing_props = []
+      missing_imports = []
+      raw_names.each do |name|
+        if pascal_case?(name)
+          missing_imports << name
+        else
+          snake = camel_to_snake(name)
+          missing_props << name unless init_set.include?(snake)
+        end
+      end
+
+      if missing_props.empty? && missing_imports.empty?
+        resolved += 1
+        next
+      end
+
+      parts = []
+      parts << "controller must pass #{missing_props.join(', ')} (not in def initialize)" if missing_props.any?
+      parts << "external constant(s) #{missing_imports.join(', ')} need import or removal" if missing_imports.any?
+      out << "#{indent}# TODO[promoted_ivar]: #{parts.join('; ')}.\n"
+      sharpened += 1
+    else
+      out << line
+    end
+  end
+
+  return { file: path, resolved: 0, sharpened: 0 } if resolved.zero? && sharpened.zero?
+
+  new_content = out.join
+  ok = Tempfile.create(['validate', '.rb']) do |tf|
+    tf.write(new_content); tf.flush
+    system('ruby', '-c', tf.path, out: File::NULL, err: File::NULL)
+  end
+
+  unless ok
+    return { file: path, resolved: 0, sharpened: 0, parse_failed: true }
+  end
+
+  { file: path, resolved: resolved, sharpened: sharpened, new_content: new_content }
+end
+
+# --- CLI --------------------------------------------------------------------
+
+opts = { dry_run: false, quiet: false }
+OptionParser.new do |o|
+  o.banner = "usage: apply_promoted_ivar.rb [--dry-run] [--quiet] <file_or_dir>..."
+  o.on('--dry-run') { opts[:dry_run] = true }
+  o.on('--quiet')   { opts[:quiet] = true }
+end.parse!(ARGV)
+
+abort "no input files" if ARGV.empty?
+
+paths = ARGV.flat_map do |arg|
+  if File.directory?(arg)
+    Dir.glob(File.join(arg, '**', '*.rb'))
+  elsif File.file?(arg)
+    [arg]
+  else
+    warn "skip: #{arg}"; []
+  end
+end
+
+totals = { files: paths.length, modified: 0, resolved: 0, sharpened: 0, parse_failed: 0 }
+paths.each do |p|
+  r = process_file(p)
+  totals[:resolved]  += r[:resolved]
+  totals[:sharpened] += r[:sharpened]
+
+  if r[:parse_failed]
+    totals[:parse_failed] += 1
+    puts JSON.generate(file: p, parse_failed: true) unless opts[:quiet]
+  elsif r[:new_content]
+    totals[:modified] += 1
+    File.write(p, r[:new_content]) unless opts[:dry_run]
+    puts JSON.generate(file: p, resolved: r[:resolved], sharpened: r[:sharpened]) unless opts[:quiet]
+  end
+end
+
+puts ''
+puts "files scanned:    #{totals[:files]}"
+puts "files modified:   #{totals[:modified]}#{opts[:dry_run] ? ' (dry-run)' : ''}"
+puts "TODOs resolved:   #{totals[:resolved]}"
+puts "TODOs sharpened:  #{totals[:sharpened]}"
+puts "parse failures:   #{totals[:parse_failed]}"