jsx_rosetta 0.5.1 → 0.6.0

data/plans/nextjs_pages_to_rails.md

@@ -0,0 +1,200 @@
+# jsx_rosetta — Next.js filesystem routing → Rails routes/controllers/views
+
+## Context
+
+The Phlex backend emits `_page.rb` files preserving the source directory structure under `pages/` — including Next.js bracket conventions (`[id]`, `[[...extra]]`) and named segments. Visually inspecting `tmp/stress/phlex_out/reserv-web/pages/` confirms the tree mirrors a Rails route table: top-level files are entry routes, named subdirectories look like resource collections, `[id]/` segments are member routes, deeper nests are nested resources.
+
+The gem already has a `Routes` module + `routes_script` backend, but those handle a **different** source: JSX `<Route path=… element={<X/>} />` declarative routes (React Router). The Next.js filesystem-routing case is unaddressed — generated Phlex pages currently land in `pages/...` without any `config/routes.rb`, controllers, or `app/views/` placement, so a user has to hand-wire the Rails side after translation.
+
+Goal: ship a deterministic, filesystem-driven path from a Next.js `pages/` directory to a usable Rails skeleton. The directory tree is the source of truth; no JS parsing is required for routing alone.
+
+## Slicing
+
+Three slices, planned separately, landed in order:
+
+1. **Slice 1 — routes only** *(this plan)*. Walk the source `pages/` tree, emit `config/routes.rb`. No file moves, no controllers, no class renames. New CLI subcommand `jsx_rosetta pages-routes`.
+
+2. **Slice 2 — controllers + view-placement** *(separate plan after slice 1 lands)*. Emit `app/controllers/<resource>_controller.rb` skeletons. Hook into `translate` so Phlex pages land at `app/views/<controller>/<action>.rb` with class `Views::<Controller>::<Action> < Views::Base` per Phlex Rails convention.
+
+3. **Slice 3 — `<Link>`/`href` rewrites to URL helpers** *(separate plan after slice 2)*. With route table from slice 1 in hand, the Phlex backend rewrites literal/simple-template hrefs (`<Link href="/claims/123">`, `<Link href={`/claims/${id}`}>`) into Rails helpers (`claim_path(123)`, `claim_path(id)`). Anything past simple template — dynamic compute, query strings, `router.push` in event handlers — stays verbatim with a TODO (handler bodies are preserved as raw JS in `IR::EventHandler` and rewriting them is the JS-to-Ruby translation territory the project avoids).
+
+This plan covers slice 1 in full. Slices 2 and 3 are sketched at the end for context only — they get their own plan files when their predecessor ships.
+
+## Slice 1 — design
+
+### Input
+
+Filesystem-only walker. Reads file paths, not contents.
+
+- Input: a directory the user points at (typically `<repo>/pages/` or `<repo>/src/pages/`).
+- File types scanned: `.tsx`, `.jsx` (and optionally `.ts`/`.js` if the user has a JS-only Next.js project; default to TSX/JSX, configurable via flag).
+- No `JsxRosetta.parse` / `JsxRosetta.lower` — the route table is fully encoded in path shape. Parsing 80+ files just to read names that we already have from `Dir.glob` would burn ~30s of Node round-trips for zero added signal.
+- Slice 2 will piggyback on the existing `translate` flow, where parse+lower already runs per file, so the AST/IR is "free" at that point.
+
+### Path → Rails route mapping
+
+Bracket segments translate to Rails params with camelCase → snake_case via `JsxRosetta::AST::Inflector.underscore`. `[providerSlug]` → `:provider_slug`, `[organizationId]` → `:organization_id`.
+
+| Source path (relative to pages/) | Rails route line | Controller#action |
+|---|---|---|
+| `index.tsx` | `root to: "pages#index"` | PagesController#index |
+| `<name>.tsx` (top-level, not `_*`) | `get "/<name>", to: "pages#<name>"` | PagesController#<name> |
+| `<res>/index.tsx` | `get "/<res>", to: "<res>#index"` | <Res>Controller#index |
+| `<res>/new.tsx` | `get "/<res>/new", to: "<res>#new"` | <Res>Controller#new |
+| `<res>/[id].tsx` | `get "/<res>/:id", to: "<res>#show"` | <Res>Controller#show |
+| `<res>/[id]/index.tsx` | `get "/<res>/:id", to: "<res>#show"` | (same — duplicate-route warning) |
+| `<res>/[id]/edit.tsx` | `get "/<res>/:id/edit", to: "<res>#edit"` | <Res>Controller#edit |
+| `<res>/[id]/<x>.tsx` | `get "/<res>/:id/<x>", to: "<res>#<x>"` | <Res>Controller#<x> |
+| `<res>/[id]/[[...extra]].tsx` | `get "/<res>/:id(/*extra)", to: "<res>#show"` | <Res>Controller#show |
+| `<res>/[id]/<sub>/[sub_id]/...` (deep) | nested params in path; controller = outermost named segment | <Res>Controller#<leaf-action> |
+| `_app.tsx`, `_document.tsx` | **skipped**; commented in output as layout files | (none) |
+| `_error.tsx`, `404.tsx`, `500.tsx` | **skipped**; commented as Rails error handlers (`config.exceptions_app`) | (none) |
+
+### Controller-name selection rule
+
+- Top-level file → `pages` controller.
+- File inside a subdirectory → controller is the **first non-bracket segment** (the outermost named directory). For `policies/[providerSlug]/[policyId]/edit.tsx`, controller is `policies`; the rest of the path becomes URL params.
+- Nested named dirs *between* the resource and the leaf — e.g., `workflows/[id]/versions/index.tsx` — get expressed as path segments, not separate controllers, in slice 1. Slice 2 may upgrade some of these to namespaces (`Workflows::Versions`) once we have the controller story figured out.
+
+### Action-name selection rule
+
+| Leaf filename | Inside one or more `[…]` dirs? | Action |
+|---|---|---|
+| `index.tsx` | no | `index` |
+| `index.tsx` | yes | `show` |
+| `new.tsx` | no | `new` |
+| `edit.tsx` | yes | `edit` |
+| `[id].tsx` (the bracket file *is* the leaf) | n/a | `show` |
+| `[[...extra]].tsx` | n/a | `show` |
+| any other `<name>.tsx` | * | `<name>` (snake_cased) |
+
+### Output
+
+A complete `config/routes.rb` — wrapped in `Rails.application.routes.draw do … end`, not a snippet. Sections:
+
+1. Header comment: source dir, generation timestamp, gem version.
+2. Skipped-files block at top, commented, with TODO markers pointing at Rails layout / error-handling counterparts.
+3. Routes grouped by controller, alphabetized. One blank line between groups. Comment header per group (`# == accounts ==`).
+4. Closing `end`.
+
+The emitted file passes `ruby -c`. Suggested companion `rails generate controller …` invocations (matching the existing `routes_script` pattern) are commented out at the bottom — copy-paste-able but not run.
+
+### Implementation
+
+New module + files. Mirrors the layout of `lib/jsx_rosetta/routes.rb` (sibling to `Routes`, not nested inside it, because the two have unrelated inputs).
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | new | `Scanner`, `Route`, `Emitter`, ~150 lines |
+| `lib/jsx_rosetta.rb` | modify | one new `require_relative "jsx_rosetta/pages_routing"` line |
+| `lib/jsx_rosetta/cli.rb` | modify | new `when "pages-routes"` branch + `run_pages_routes` method + help text update |
+| `lib/jsx_rosetta/ir/types.rb` | unchanged | no new IR types needed for slice 1 |
+
+Internal shapes:
+
+```ruby
+module JsxRosetta
+  module PagesRouting
+    Route = Data.define(:rails_path, :controller, :action, :source_path)
+    Skipped = Data.define(:source_path, :reason)
+
+    module Scanner
+      def self.scan(dir, extensions: %w[.tsx .jsx])
+        # walks dir, returns [routes:, skipped:]
+      end
+    end
+
+    module Emitter
+      def self.emit(routes:, skipped:, source_dir:)
+        # returns String (full routes.rb contents)
+      end
+    end
+  end
+end
+```
+
+### Existing utilities to reuse
+
+- `JsxRosetta::AST::Inflector.underscore` — for camelCase → snake_case on param names and controller names (already does the right thing for `providerSlug` → `provider_slug`).
+- The existing `RoutesScript` backend's output template (header comment style, `rails generate` invocation phrasing) — copy the style, don't share code, since their inputs differ. Match phrasing for consistency.
+
+### Specs
+
+Match the existing flat-spec convention (`spec/routes_spec.rb`, `spec/cli_spec.rb` are both single files, not directories).
+
+| Path | Status | Coverage |
+|---|---|---|
+| `spec/pages_routing_spec.rb` | new | Scanner: each row of the mapping table (~15 examples). Emitter: ordering, grouping, comment headers, skipped-files block (~6 examples). Use `Dir.mktmpdir` + `FileUtils.touch` to build synthetic trees. |
+| `spec/cli_spec.rb` | modify | New describe block for `pages-routes` subcommand (~3 examples: happy path, missing dir error, `-o` flag). |
+
+Edge cases worth one spec each:
+- Empty `pages/` dir → emit an empty `routes.rb` (with header comment) without crashing.
+- `pages/` with only `_app.tsx`, `_document.tsx` → all-skipped output; route table empty.
+- `pages/` with a single `index.tsx` → exactly one `root` line.
+- Deep nesting (`pages/policies/[providerSlug]/[policyId]/edit.tsx`) → param order preserved, snake_case applied to both.
+- `[...rest]` non-optional rest catch-all — not seen in the stress corpus; treat as `*rest` (no parens) and add one spec.
+
+### CLI surface
+
+```
+jsx_rosetta pages-routes <pages-dir> [-o <path>] [--ext .tsx,.jsx,.ts,.js]
+```
+
+Defaults: `-o` writes to stdout if absent; `--ext` defaults to `.tsx,.jsx`. Help text updated in `print_help`.
+
+### Verification
+
+```bash
+cd /home/sean/code/jsx_rosetta
+bundle exec rspec spec/pages_routing_spec.rb spec/cli_spec.rb
+bundle exec rubocop lib/jsx_rosetta/pages_routing.rb lib/jsx_rosetta/cli.rb spec/pages_routing_spec.rb
+bundle exec rake # full default suite
+
+# Round-trip against the stress corpus' page directory shape.
+# (The stress run emits .rb files, but the bracket directory names
+# carry the same Next.js shape — point the scanner at them with --ext .rb
+# to confirm the path classifier handles real-world depth.)
+bundle exec exe/jsx_rosetta pages-routes tmp/stress/phlex_out/reserv-web/pages \
+  --ext .rb -o /tmp/routes.rb
+ruby -c /tmp/routes.rb   # must succeed
+wc -l /tmp/routes.rb     # ballpark: ~100 route lines for ~80 leaf files
+```
+
+Spot-check 5 routes by hand against the original `pages/...` paths to confirm controller + action selection.
+
+## Slice 2 sketch (separate plan, after slice 1)
+
+Coupled changes — best landed together so the controller's `render` call references the relocated view class:
+
+1. **Controller emission**: for each unique controller from slice 1's route table, emit `app/controllers/<controller>_controller.rb` with one empty `def <action>; end` per action. Add a `before_action` TODO comment listing the URL params (`:id`, `:provider_slug`, etc.). Skip emission if the controller file already exists (never clobber user code).
+
+2. **View relocation + class rename**: change the Phlex backend so when it knows it's running with a route map (via a `--rails-routes <pages-dir>` flag or a `JsxRosetta.translate` option), it routes each page file to `app/views/<controller>/<action>.rb` instead of preserving the source directory shape, and renames the class from `<Foo>Page` to `Views::<Controller>::<Action>` with parent `Views::Base`. The Phlex Rails docs ([phlex.fun/rails/layouts](https://www.phlex.fun/rails/layouts)) confirm `Views::Articles::Index < Views::Base` (which inherits from `Phlex::HTML`) at `app/views/articles/index.rb` is the canonical shape.
+
+Deferred to that plan: action-name collisions, namespace nesting (`pages/admin/users/...` → `Admin::UsersController`?), the `_app.tsx`/`_document.tsx` → application-layout component handling, optional detection of `getServerSideProps` to mark controller actions as needing data-fetching TODOs (the only place AST/IR meaningfully helps).
+
+## Slice 3 sketch (separate plan, after slice 2)
+
+URL-helper rewrite in the Phlex backend:
+
+- `<Link href="/claims/123">` → `link_to "...", claim_path(123)` when `/claims/:id` is in the route table.
+- `<Link href={`/claims/${claim.id}`}>` → match the template literal's static segments against the route table; rewrite if exactly one route matches with one `:id`-shaped hole.
+- `<Link href={someComputed}>` → leave verbatim + TODO.
+- `router.push("/claims/...")` in event handlers — **skipped** (handler bodies are preserved JS in `IR::EventHandler`; rewriting requires a JS-AST pass which conflicts with the "no speculative JS-to-Ruby translation" project rule).
+
+Practicality: literal & simple-template href rewrites are deterministic and high-value (every `<Link>` to a known resource gets idiomatic Rails). Anything past that stays verbatim. Worth doing once the route table is real.
+
+## Out of scope for slice 1
+
+- Controller skeletons (slice 2).
+- View relocation / rename (slice 2).
+- `<Link>` / `href` → URL helper rewrites (slice 3).
+- `getServerSideProps` / `getStaticProps` detection — would require AST parsing per file. Belongs in slice 2 if at all.
+- Route groups like `(group)/` — none in the stress corpus; defer until encountered.
+- Application-layout / error-handler emission for `_app.tsx`, `_document.tsx`, `_error.tsx` — slice 1 just lists them as TODO comments at the top of the emitted `routes.rb`.
+- Sharing infrastructure with the existing `RoutesScript` backend — they have different inputs and different output shapes; deduplicate later if both grow.
+
+## Risks
+
+- **Action name collisions across files.** Two leaves in the same controller may both want the same action name (e.g., a `[id]/edit.tsx` and a `new_edit.tsx` both wanting `edit`). Scanner detects, emits a duplicate-route warning comment in the output, picks one and suffixes the other with `_2`. Spec covers this.
+- **Deeply-nested resources don't fit Rails REST naming.** `pages/policies/[providerSlug]/[policyId]/edit.tsx` becomes `policies#edit` with two URL params — semantically right, but a Rails dev might expect a `PoliciesProvidersPoliciesController`. Slice 1 deliberately punts on this — emit the flat route, let the user reshape in slice 2 if they want.
+- **Files outside the pages root.** If the user points at a parent of `pages/`, the scanner will treat every `.tsx` file as a top-level page. Scanner errors out if `<dir>` doesn't end in `pages` (or contain a `pages/` subdir) unless `--allow-any-dir` is passed.

data/plans/nextjs_pages_to_rails_slice_2.md

@@ -0,0 +1,118 @@
+# jsx_rosetta — slice 2: controller skeletons + Phlex view placement
+
+Builds on slice 1 (`pages-routes` → routes.rb). Slice 1 produced the route table; this slice consumes it to (a) emit controller files matching the route table and (b) reshape Phlex backend output to match Rails view conventions.
+
+Parent plan: `plans/nextjs_pages_to_rails.md` (slice 2 sketch section).
+
+## Two coupled deliverables
+
+These ship together because the controller's `render` (implicit) references the view class that view-placement renames.
+
+### A. Controller emission
+
+For each unique `controller` in the route table:
+
+- Emit `app/controllers/<controller>_controller.rb`.
+- One empty `def <action>; end` per route in that controller, alphabetized.
+- Comment above each action listing URL params extracted from the matching `rails_path` (e.g. `# params: :id, :provider_slug`).
+- Skip emission entirely if the file already exists on disk (never clobber user code — emit a stderr note).
+- Parent class: `ApplicationController` (Rails convention; user is expected to have it).
+
+### B. Phlex view placement
+
+New backend option `rails_view:` on `Backend::Phlex`. When set to a route entry (responding to `controller` and `action`):
+
+- File path: `<controller>/<action>.rb` (slot under `app/views/` at the CLI level).
+- Class name: `Views::<ControllerCamel>::<ActionCamel>`.
+- Parent class: `Views::Base` (user-defined per Phlex Rails convention; reference [phlex.fun/rails/layouts](https://www.phlex.fun/rails/layouts)).
+
+The existing `suffix:` / `namespace:` Phlex options are mutually exclusive with `rails_view:` — error out if combined.
+
+The page-aware `effective_suffix_for` / `page?` helpers added in v0.5.x stop applying when `rails_view:` is set — the Rails convention takes precedence.
+
+## CLI surface
+
+### Extended `pages-routes`
+
+```
+jsx_rosetta pages-routes <pages-dir> [-o routes.rb] [--controllers DIR] \
+                                     [--ext .tsx,.jsx] [--allow-any-dir]
+```
+
+`--controllers DIR` is independent of `-o`. When set:
+
+- Writes one `<controller>_controller.rb` per controller into `DIR`.
+- Prints `wrote <path>` lines to stdout.
+- Skips files that already exist; prints `skipped <path> (exists)`.
+
+### Extended `translate`
+
+```
+jsx_rosetta translate <file.tsx> --as=phlex --rails-routes <pages-dir> -o <views-dir>
+```
+
+When `--rails-routes` is set:
+
+- Scans `<pages-dir>` to build a route lookup once.
+- Resolves `<file>`'s path relative to `<pages-dir>`. Error if the file is not under it.
+- Looks up the route by source path. Error if the file is not represented in the table (e.g., skipped `_app.tsx`).
+- Passes `rails_view: Route` as a Phlex backend option.
+- Output lands at `<views-dir>/<controller>/<action>.rb`.
+
+`--rails-routes` is invalid without `--as=phlex` (ViewComponent + RailsView backends are out of scope for this slice).
+
+`--rails-routes` is invalid combined with `--phlex-suffix` / `--phlex-namespace`.
+
+## Implementation
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/pages_routing.rb` | modify | New `Emitter.emit_controllers(routes:)` returning `[File-like]`. Action-name camelization helpers. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | Accept `rails_view:` option. Override `class_name`, parent class, and file path when set. |
+| `lib/jsx_rosetta.rb` | modify | Surface `rails_view:` in `backend_options.slice` allowlist for the Phlex backend. |
+| `lib/jsx_rosetta/cli.rb` | modify | `--controllers DIR` on pages-routes; `--rails-routes DIR` on translate. |
+
+### URL-param extraction for controller comments
+
+From a `rails_path` like `/policies/:provider_slug/:policy_id/edit`, strip everything that isn't a `:param` token: `[:provider_slug, :policy_id]`. Catch-all params (`*rest`, `(/*extra)`) included as `*rest`-style entries. Emitted as `# params: :provider_slug, :policy_id` above the action.
+
+### Class-name camelization
+
+`AST::Inflector.camelize` returns lowerCamelCase. For class names this slice needs UpperCamelCase. Add `AST::Inflector.upper_camelize` (or inline `parts.map(&:capitalize).join`) — pick whichever keeps the inflector module focused.
+
+## Specs
+
+| Path | Status | Coverage |
+|---|---|---|
+| `spec/pages_routing_spec.rb` | modify | `Emitter.emit_controllers` shape, action ordering, param comments, skip-on-exists is a CLI concern not module concern (covered in cli_spec). |
+| `spec/backend/phlex_spec.rb` | modify | `rails_view:` option overrides class + parent + path; mutual-exclusion errors with `suffix:` / `namespace:`. |
+| `spec/cli_spec.rb` | modify | `pages-routes --controllers DIR`: writes per-controller files, skips existing; `translate --rails-routes <pages-dir>`: writes view to `<controller>/<action>.rb`, errors when file is outside pages-dir, errors when file is skipped. |
+
+## Verification
+
+```bash
+cd /home/sean/code/jsx_rosetta
+bundle exec rake
+
+# Round-trip a real page through the new pipeline.
+ruby -Ilib exe/jsx_rosetta pages-routes tmp/stress/phlex_out/reserv-web/pages \
+  --ext .rb -o /tmp/routes.rb --controllers /tmp/controllers
+ls /tmp/controllers
+ruby -c /tmp/controllers/*.rb
+```
+
+Spot-check a few generated controllers against the route table to confirm action lists, param comments, and class names.
+
+## Out of scope (deferred to future slices or punted)
+
+- Namespace nesting (`pages/admin/users/...` → `Admin::UsersController`). Keep flat controllers for slice 2; revisit if it bites.
+- `_app.tsx` / `_document.tsx` → application-layout class. The skipped-files block in slice 1's routes.rb already flags these.
+- `getServerSideProps` / `getStaticProps` detection — requires AST per file. Not in slice 2.
+- Action-name collisions across files in the same controller — slice 1 already dedupes identical routes; cross-path collisions remain rare. Punt to slice 3 or later.
+- `--rails-routes` for non-Phlex backends — slice 3+ if needed.
+
+## Risks
+
+- **`Views::Base` not defined.** User must add it themselves per Phlex Rails docs. We emit a one-line `# TODO: ensure app/views/base.rb defines Views::Base < Phlex::HTML` comment at the top of each view file. No autogeneration of `Views::Base` — out of scope.
+- **Controller file already exists.** Slice 2 skips with a stderr note rather than clobbering. Risks: user may not realize their controller is out of sync with the new routes. Mitigation: stderr message lists which actions the routes.rb expects so they can reconcile.
+- **`ApplicationController` missing.** Same as above — emit referencing it; user wires up.

data/plans/nextjs_pages_to_rails_slice_3.md

@@ -0,0 +1,121 @@
+# jsx_rosetta — slice 3: `<Link>` / `href` → Rails URL helpers
+
+Builds on slices 1 (`pages-routes` → routes.rb) and 2 (controller skeletons + Phlex view placement). With the route table now available end-to-end through the `--rails-routes` flag, the Phlex backend can rewrite literal/simple-template URLs into matching Rails URL helpers.
+
+Parent plan: `plans/nextjs_pages_to_rails.md` (slice 3 sketch).
+
+## What gets rewritten
+
+Only the `href` (or `to`) attribute on tags whose name is `a`, `Link`, `NavLink`, or `RouterLink`:
+
+| Source | Rewritten to | Notes |
+|---|---|---|
+| `<a href="/accounts">` | `a(href: accounts_path)` | exact path match against route table |
+| `<Link href="/accounts/123">` | `Link(href: account_path(123))` | numeric literals pass through as integer |
+| `<Link href={`/accounts/${id}`}>` | `Link(href: account_path(id))` | single `:id`-shaped hole matched against an identifier or member expression |
+| `<Link href={`/policies/${slug}/${policyId}/edit`}>` | `Link(href: edit_policy_path(slug, policy_id))` | multi-param simple template |
+| `<Link href={someComputed}>` | unchanged + `# TODO:` | not deterministic |
+| `<a href="https://external.example">` | unchanged | external URL — absolute scheme |
+| `<a href="#anchor">` | unchanged | fragment-only |
+| `router.push("/foo")` in handlers | unchanged | handler bodies are preserved JS (`IR::EventHandler`) — out of scope per project rule against speculative JS-to-Ruby translation |
+
+## URL helper naming
+
+Helpers and `as:` names are derived from `(controller, action, rails_path)` by a single function so slice 1's routes.rb and slice 3's rewrites stay paired:
+
+| Controller / action / path | `as:` token | Helper |
+|---|---|---|
+| `(pages, index, "/")` | `:root` | `root_path` |
+| `(accounts, index, _)` | `:accounts` | `accounts_path` |
+| `(accounts, show, _)` | `:account` | `account_path(*params)` |
+| `(accounts, new, _)` | `:new_account` | `new_account_path` |
+| `(accounts, edit, _)` | `:edit_account` | `edit_account_path(*params)` |
+| `(accounts, <other>, _)` | `:accounts_<other>` | `accounts_<other>_path(*params)` |
+
+Singularization uses a small new `AST::Inflector.singularize`:
+- `accounts` → `account`, `policies` → `policy`, `boxes` → `box`, `dishes` → `dish`, `houses` → `house`.
+- Irregular plurals (`children`, `people`) are returned as-is — the user can fix the `as:` in routes.rb and re-run translate if needed.
+
+## Slice 1 routes.rb change
+
+`Emitter.route_line` adds `, as: :<name>` to each route line. This is a **behavior change** for the existing slice 1 output, so the slice 1 specs are updated alongside the new slice 3 specs. `root` route stays as `root to: "pages#index"` (Rails always names that `root`).
+
+## Implementation
+
+| Path | Status | Scope |
+|---|---|---|
+| `lib/jsx_rosetta/ast/inflector.rb` | modify | New `.singularize` (simple `ies`/`ses`/`s` rules). |
+| `lib/jsx_rosetta/pages_routing.rb` | modify | New `Naming` module + `HrefRewriter` class. `Emitter.route_line` adds `as:`. |
+| `lib/jsx_rosetta/backend/phlex.rb` | modify | New `route_table:` initializer kwarg. Thread `tag:` through `format_attributes` → `attribute_value_to_ruby`. Add the rewrite path. |
+| `lib/jsx_rosetta.rb` | modify | Allowlist `route_table:` in the Phlex backend options slice. |
+| `lib/jsx_rosetta/cli.rb` | modify | `resolve_rails_view_route!` also captures the full route table and forwards it via `options[:route_table]`. |
+
+## HrefRewriter
+
+```ruby
+module JsxRosetta
+  module PagesRouting
+    class HrefRewriter
+      def initialize(routes)
+        # Builds an internal index keyed by (segment-shape) → route.
+      end
+
+      # value: a String (verbatim path), or { kind: :template, literal_segments: [...], holes: [ruby_expr, ...] }
+      # Returns: a Ruby source string (e.g. "account_path(id)") or nil.
+      def rewrite(value)
+      end
+    end
+  end
+end
+```
+
+Matching algorithm:
+- Split both the input path and each route's `rails_path` by `/`.
+- For each route, walk segments together: literal must equal, `:foo`/`(/*foo)`/`*foo` consumes the corresponding input segment(s).
+- A single route must match (no ambiguity) — if multiple match, return nil (bail to verbatim + TODO).
+- For literal input, the consumed segment value becomes a Ruby integer literal if `\A-?\d+\z`, else a Ruby string literal.
+- For template input, the consumed segment value is the corresponding hole's Ruby expression.
+
+## Phlex backend wiring
+
+`@route_table` and `@href_rewriter` are stored on the backend instance during `initialize`. The `tag:` kwarg is plumbed through `format_attributes` → `append_attribute_part` → `phlex_attribute_part` → `plain_attribute_part` → `attribute_value_to_ruby`.
+
+`attribute_value_to_ruby` short-circuits when (a) `@href_rewriter` is set, (b) tag is link-shaped (`a`, `Link`, `NavLink`, `RouterLink`), (c) name is `href` or `to`, (d) the value is a String or IR::Interpolation containing a string/template literal. The rewriter returns Ruby; otherwise we fall through to the existing behavior unchanged.
+
+## Specs
+
+- `spec/ast/inflector_spec.rb` (or wherever inflector specs live): `.singularize` table.
+- `spec/pages_routing_spec.rb`: `Naming` table + `HrefRewriter` (literal match, template match, ambiguity, external/absent → nil) + slice 1 `Emitter` updates (`as:` lines).
+- `spec/backend/phlex_spec.rb`: end-to-end Phlex `route_table:` test cases.
+- `spec/cli_spec.rb`: `translate --rails-routes` produces a view with rewritten hrefs.
+
+## Verification
+
+```bash
+cd /home/sean/code/jsx_rosetta
+bundle exec rake
+
+# Round-trip
+ruby -Ilib exe/jsx_rosetta pages-routes tmp/stress/phlex_out/reserv-web/pages \
+  --ext .rb -o /tmp/r3/routes.rb
+grep -c 'as: :' /tmp/r3/routes.rb  # expect ~82 lines
+
+# Synthetic href test
+# (TSX with literal + template hrefs, translate with --rails-routes,
+#  inspect the emitted view for `*_path` calls.)
+```
+
+## Out of scope
+
+- Rewriting `href` on tags other than `a`/`Link`/`NavLink`/`RouterLink`.
+- `<form action="/post">`-style action rewrites.
+- `router.push("/x")` inside event handler bodies — preserved verbatim per project rule.
+- Re-running `pages-routes` automatically when `translate` is invoked — user must keep their routes.rb in sync (the route table is scanned each `translate` call; only the routes.rb file on disk lags if the user doesn't re-run pages-routes).
+- Anchor / query-string fragments. A path like `"/accounts#tab=details"` is left verbatim.
+- Multi-route disambiguation by HTTP method (we only emit GET routes anyway).
+
+## Risks
+
+- **Slice 1 `as:` change is a breaking diff for any existing routes.rb consumers.** Mitigated by updating the slice 1 specs and including the change in the same commit so the gem's behavior is consistent.
+- **Bad singularization** (e.g. `mice` → `mic`). Mitigated by emitting a TODO comment above the view file the first time a non-trivial helper is used, listing the helper names so the user can compare against their routes.rb.
+- **False matches.** If the user has `/accounts` and `/accounts_list`, a literal `/accounts_list` would not match `/accounts` (segment equality), so this is safe. The bigger risk: a template literal `/foo/${x}` where multiple routes have `/foo/:id`-shapes — slice 3 bails (returns nil) on ambiguity.