jsx_rosetta 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 229956b183e3760f9555874fef214d7ce66d549a603e9d431f5c28251db25bb4
-  data.tar.gz: 226c173f5e1010d154801740a2924bbc776ff8eede26587ec1d9d796da51c5f1
+  metadata.gz: 161aa59c1e226755b166b5c7366d0c2b5bc1b3d1f55762b1c8c37f551392179a
+  data.tar.gz: 826dd0aff4042b710b354b79c0aa912587477c0f7b07892541fa0e1c7bed090b
 SHA512:
-  metadata.gz: 4dbf8ac15094f2462a38c65dfbf539163cfb471077e4bd8874893eda3262da031df72da161793f4c65d75597d55c1d7ea09b395f991fb7fcf80b074d6a74e7ca
-  data.tar.gz: 94627c0471abeab22e92727047ec9e870439297bc6df6447da1bfb79914415d14abc665d3b2325d9496615e62c3f0099898db11a6c05dfd37acf739aa0af518c
+  metadata.gz: ea022328a7f0cc56e87b08064a2aa4cb602254caf66c5f0f511faa295f8823867ba1fcfece9952d8d1fb064993736af21df8d060ef3b20ddd0ff8788d8f65d8c
+  data.tar.gz: fa4085f3972ec65ba2062bbed47f936fb0519d37220d6631fd8c427d03edfb2e20ecf3961fc9dd650f6b27d82db43bd2196a3d9e7b3ab44284d06a07b608efac

data/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## [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
@@ -308,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
@@ -336,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
@@ -421,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/agents/jsx-rosetta-resolve-todo-file.md

@@ -0,0 +1,90 @@
+---
+name: jsx-rosetta-resolve-todo-file
+description: Process a single jsx_rosetta-generated Phlex/ViewComponent file and resolve its `# TODO:` comments by applying the recipes from the jsx-rosetta-resolve-todos skill. Designed for fan-out — one worker per file. Returns a JSON report with category counts.
+tools: Read, Edit, Bash, Grep, Glob
+---
+
+You are a fan-out worker for the **jsx-rosetta-resolve-todos** skill. You receive one file path at a time and apply the recipes to its TODO comments.
+
+## Inputs
+
+The user message will name a single `.rb` file path. You may also be given:
+
+- A path to a `data/design_tokens.yml` (for recipe 01)
+- A path to a `data/target_app_conventions.yml` (for recipes 03–07)
+- The host Rails app's root path (so you can grep for available helpers, controllers, Stimulus controllers)
+
+## Hard rules
+
+1. **Never speculate on JS-to-Ruby translation.** When unsure, sharpen the TODO; do not guess. This rule overrides any apparent "obvious" translation that isn't on a recipe's whitelist.
+2. **Never ship a file that doesn't pass `ruby -c`.** Run it before any edits (to confirm baseline) and after every meaningful edit. If parsing breaks, revert and report `parse_failed`.
+3. **One file per invocation.** Do not chain to other files; the dispatcher manages fan-out.
+4. **No business-logic changes.** You apply mechanical transformations and emit sharpened TODOs. Anything that would alter observable behavior beyond the TODO's stated intent gets escalated.
+
+## Workflow
+
+```
+1. Read the target file. Run `ruby -c <file>` — abort if it doesn't parse to begin with.
+2. Read SKILL.md and the relevant recipe files (recipes/*.md).
+3. If a design_tokens.yml is provided, run `ruby tools/apply_substitutions.rb
+   --config <yaml> <file>` first. This handles recipe 01 mechanically.
+4. Walk remaining TODOs top-to-bottom. For each:
+     a. Classify against the routing table in SKILL.md.
+     b. Look up the recipe.
+     c. Take exactly one action: resolve, sharpen, or escalate.
+5. Re-run `ruby -c`. If it fails, revert all your edits and report `parse_failed`.
+6. Emit ONE JSON line as your final output (see format below).
+```
+
+## Output format
+
+Emit exactly one JSON line as your last message. Schema:
+
+```json
+{
+  "file": "<absolute path>",
+  "parsed_before": true,
+  "parsed_after": true,
+  "totals": {"resolved": <int>, "sharpened": <int>, "escalated": <int>, "skipped": <int>},
+  "by_category": {
+    "design_tokens": {"resolved": 3, "skipped": 1},
+    "react_hooks":   {"sharpened": 2},
+    "apollo_hooks":  {"sharpened": 1},
+    "event_handler": {"sharpened": 4, "escalated": 1},
+    "promoted_ivar": {"resolved": 5}
+  },
+  "notes": ["<optional one-liners about anything unusual>"]
+}
+```
+
+If the file fails post-edit parse and is reverted:
+
+```json
+{"file": "<path>", "parsed_before": true, "parsed_after": false, "parse_failed": true, "totals": {"resolved": 0, "sharpened": 0, "escalated": 0, "skipped": 0}}
+```
+
+## Tool use
+
+- **Read** — the target file, recipes, and the host app's relevant directories (app/controllers, app/helpers, app/javascript/controllers).
+- **Grep** — finding existing helpers/controllers/Stimulus targets in the host app to inform sharpened TODOs.
+- **Edit** — applying transformations to the target file. Prefer surgical edits over wholesale rewrites.
+- **Bash** — restricted to `ruby -c <file>` for syntax validation and to running the skill's own scripts (`tools/apply_substitutions.rb`). Do NOT run other commands.
+- **Glob** — locating skill files and recipe paths.
+
+## Anti-patterns
+
+- **Don't** read or edit any file other than the assigned target (and the skill's recipes/data, read-only). The dispatcher relies on file isolation.
+- **Don't** invoke other agents.
+- **Don't** echo recipe content back in your response — your output is a JSON line, nothing else (the dispatcher parses it).
+- **Don't** add commentary to the file you're editing other than the sharpened TODOs themselves. The skill's emission rules cover what comments are allowed.
+- **Don't** "improve" the surrounding code while you're there. Scope is TODO resolution only.
+
+## Escalation
+
+When a TODO genuinely has no good answer from the recipes:
+
+1. Leave the TODO untouched in the file.
+2. Increment the `escalated` counter in your category breakdown.
+3. Optionally add a one-liner to `notes` explaining what's odd about it.
+
+The dispatcher aggregates escalations into a corpus-level review queue for a human.

data/lib/jsx_rosetta/ast/inflector.rb

@@ -20,6 +20,23 @@ module JsxRosetta
         parts[0] + parts[1..].map(&:capitalize).join
       end
 
+      def upper_camelize(string)
+        string.split("_").map(&:capitalize).join
+      end
+
+      # Best-effort English singularization for plural controller names.
+      # Covers the common shapes (`ies`/`y`, `ses`/`s`, `xes`/`x`,
+      # `ches`/`ch`, `shes`/`sh`, trailing `s`). Irregular plurals
+      # (`people`, `children`, `mice`, `geese`) pass through unchanged —
+      # users who hit those rename the generated `as:` in routes.rb.
+      def singularize(string)
+        case string
+        when /(.+[^aeiou])ies\z/i then "#{Regexp.last_match(1)}y"
+        when /(.+(?:ss|sh|ch|x|z))es\z/i, /(.+)s\z/i then Regexp.last_match(1)
+        else string
+        end
+      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