Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,31 @@

## [Unreleased]

- **HAML support**: `.haml` views and partials are converted alongside `.erb`
(`convert app/views` picks up both; `convert_string(..., format: :haml)`).
A new front-end (`HamlParser`) uses the haml gem's own parser — an
*optional* dependency, required lazily, supporting haml 5.2/6.x/7.x — and
builds the same AST as the ERB front-end, so RubyUI mapping, `link_to`/
`render`, form-builder mapping, locals/ivars detection and `--literal`
apply unchanged. Covers tags/shorthand, `=`/`!=`/`&=`, control flow and
blocks, interpolated text (parsed as HTML, so inline markup and
`#{link_to ...}` convert too), attribute merging (`class`/`id`, literal
`data:`/`aria:` hashes, booleans, `[@obj]` → `dom_id`/`dom_class`, splats),
comments (`/` with nested content → `comment do … end`), doctype and the
`:javascript`/`:css`/`:plain`/`:escaped`/`:erb`/`:ruby` filters. Without
the haml gem, the CLI explains once how to add it.
- The end-to-end check also scaffolds a resource with haml-rails and renders
its converted HAML views.
- Two templates generating the same `.rb` (`show.html.erb` + `show.html.haml`,
or a `+variant`) are now reported as an error instead of being skipped or
overwritten.
- Fix: `form_with model: @x do |form|` (unparenthesized) now activates the
form-builder mapping (the model capture swallowed `do |form|`).
- Fix: a same-line space between inline siblings (`<em>a</em> <%= b %>`) is
kept as Phlex `whitespace` instead of being dropped.
- Attribute expressions that are already self-delimited (`[a, b]`, `{...}`,
`dom_id(user, :row)`) are no longer wrapped in parentheses.

- Compatibility matrix in the README and in CI: unit tests on Ruby 3.0–4.0
(plus `ruby-head`), and an end-to-end check (`script/rails_e2e/run.sh`) that
scaffolds, converts and renders a fresh Rails 7.1/7.2/8.0/8.1 app on
Expand Down
25 changes: 17 additions & 8 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

## What this is

A Ruby gem (no native dependencies, only `thor` at runtime) that converts Rails `.erb` views/partials into Phlex/RubyUI component classes. It is a heuristic source-to-source tool: `app/views/users/index.html.erb` → `app/views/users/index.rb` (`Views::Users::Index`). Partials (`_user.html.erb`) become their own classes with detected locals as keyword arguments; top-level views get an initializer built from the controller instance variables they reference. By default, basic HTML elements are mapped onto RubyUI kit components (`a[href]`→`Link(...)`, `button`→`Button(...)`, `input`→`Input(...)`, the table family, etc.); `ruby_ui: false` / `--no-ruby-ui` emits plain Phlex elements instead.
A Ruby gem (no native dependencies, only `thor` at runtime) that converts Rails `.erb` and `.haml` views/partials into Phlex/RubyUI component classes. It is a heuristic source-to-source tool: `app/views/users/index.html.erb` (or `.html.haml`) → `app/views/users/index.rb` (`Views::Users::Index`). Partials (`_user.html.erb`) become their own classes with detected locals as keyword arguments; top-level views get an initializer built from the controller instance variables they reference. By default, basic HTML elements are mapped onto RubyUI kit components (`a[href]`→`Link(...)`, `button`→`Button(...)`, `input`→`Input(...)`, the table family, etc.); `ruby_ui: false` / `--no-ruby-ui` emits plain Phlex elements instead.

## Commands

Expand All @@ -21,32 +21,38 @@ Release tasks come from `bundler/gem_tasks` (`rake build`, `rake release`).

## Architecture: the conversion pipeline

The whole gem is a single linear pipeline; each stage is one file in `lib/ruby_ui_converter/`:
The gem is a linear pipeline with **two front-ends that build the same `Nodes` AST**; each stage is one file in `lib/ruby_ui_converter/`:

```
ERB source ─▶ Lexer ─▶ HtmlTokenizer ─▶ Parser ─▶ Transformer ─▶ Ruby/Phlex source
(ERB tokens + (html tokens) (Nodes AST) (writes into CodeBuilder)
placeholders)
ERB source ─▶ Lexer ─▶ HtmlTokenizer ─▶ Parser ─────┐
(ERB tokens + (html tokens) ├─▶ Nodes AST ─▶ Transformer ─▶ Ruby/Phlex source
placeholders) │ (writes into CodeBuilder)
HAML source ─▶ Haml::Parser (haml gem) ─▶ HamlParser ┘
```

`RubyUIConverter.parse(source, format:)` is the single dispatch point (`FORMATS` maps `.erb`/`.haml` → `:erb`/`:haml`; `format_for(path)`); `Template#format` derives it from the extension and `FileWalker` globs `**/*.{erb,haml}` (keep the glob in sync with `FORMATS`). Everything after the AST is shared, so a fix in the Transformer/helpers applies to both formats — and a HAML front-end feature should be expressed as the AST the equivalent ERB would produce, not as Transformer special cases.

The key trick that makes this work without a real HTML5 parser: **`Lexer` replaces every ERB tag with an alphanumeric placeholder** (`RUCxERBx<n>xERBxRUC`) and keeps a registry of placeholder → `Lexer::Token`. The placeholder uses only word characters, so ERB inside tags and attribute values survives `HtmlTokenizer` as inert text. `Parser` then resolves placeholders back into ERB nodes while building the AST.

Other pieces around the pipeline:

- **HAML front-end** — `haml_parser.rb` walks `Haml::Parser`'s ParseNode tree (`Haml::Parser.new(escape_html: true).call(src)`; same tree shape on haml 5.2/6/7). The haml gem is an **optional dependency**: never `require "haml"` at load time — `HamlParser.load_haml!` requires it lazily (via the `require_haml` seam tests stub) and raises `Error` with `HamlParser::MISSING_HAML`, which the CLI reports once. Facts the code relies on: `escape_html: true` is what distinguishes `=` from `!=`; `else`/`elsif`/`when` arrive *flattened among the children* of their `if`/`case` node (`control` splits them into Branches); script text has a leading space; interpolated text arrives as a dumped Ruby string literal, flagged `escape_interpolation` (haml 6/7) or only recognizable by the escape wrappers haml 5/6 put around each interpolation (`ESCAPE_WRAPPER`, stripped by `unwrap_escape`). HAML text (plain lines, inline tag text, `:plain`) is turned into an ERB snippet (`#{x}` → `<%= x %>`) and run through the ERB `Parser` (`text_nodes`), so inline HTML becomes elements and interpolated helpers/locals are visible downstream. `convert_children` pads text next to rendered siblings with a space (HAML's newline), skipping silent nodes and `%tag>` (nuke outer whitespace). `/` comments keep nested content as `Comment#children` (→ `comment do … end`); `/[if IE]` and unknown filters become `# TODO` comments.
- **`haml_attributes.rb`** — HAML tag attributes → the `[[name, parts]]` list. Sources in order: static (`attributes` hash), `dynamic_attributes.new` (html-style), `.old` (`{}` hash — static literal hashes stay here too), then `object_ref` (`dom_id`/`dom_class`). Hashes are split with `Haml::AttributeParser.parse` (nil → `**(...)` splat). `class` values merge (all strings → one string; any expression → `[static, expr]` array, which Phlex flattens), `id` joins with `_`, others are overridden; `false`/`nil` drop, `true` is boolean, symbols become text, literal `data:`/`aria:` hashes expand to hyphenated keys.
- **`ruby_literal.rb`** — `RubyLiteral.string_parts(code)`: Ripper-based split of a single string literal into `[:text, s]`/`[:code, expr]` (nil for anything else). Decodes escapes via `String#undump`, \u-escaping raw non-ASCII first (undump rejects it). No haml dependency.
- **`nodes.rb`** — AST node types. Attribute values are stored as "parts" arrays of `[:text, "literal"]` / `[:erb, token]` entries, which is how the Transformer decides between a plain string, a bare Ruby expression, or an interpolated string for an attribute. `<% if %>`/`each do` become `Nodes::Control` with `Branch` children (so output is real Ruby control flow, not strings). `Element#static_attr(name)` / `#static_classes` / `#attr?` are the matcher API for ComponentMap rules (they return nil/[] when the value contains ERB).
- **`transformer.rb`** — walks the AST, emits Phlex method calls. Before emitting a plain element it consults `config.component_map.lookup(node)`; a matching rule's emitter takes over. Its public helpers (`emit_children`, `render_attrs`, `meaningful`, `kit_component`, `wrap_component`, `component_block`) form the API that ComponentMap emitters use. `kit_component` emits Phlex::Kit-style calls (`Link(href: x) { ... }`, always parenthesized; `void: true` for Input-like components).
- **`transformer.rb`** — walks the AST, emits Phlex method calls. Before emitting a plain element it consults `config.component_map.lookup(node)`; a matching rule's emitter takes over. Its public helpers (`emit_children`, `render_attrs`, `meaningful`, `kit_component`, `wrap_component`, `component_block`) form the API that ComponentMap emitters use. `kit_component` emits Phlex::Kit-style calls (`Link(href: x) { ... }`, always parenthesized; `void: true` for Input-like components). `meaningful` drops whitespace-only text *except* a same-line space between two siblings (`inline_space?` → emitted as Phlex `whitespace`); `bare_expression` only parenthesizes attribute expressions that contain whitespace and aren't `self_delimited?` (bracket literals / parenthesized calls).
- **`component_map.rb`** — two-layer registry of `{matcher: ->(Element){bool}, emitter: ->(el, transformer, builder){}}` rules: user rules (`register`) always win over fallback rules (`register_fallback`). `ComponentMap.rubyui_rules` installs the built-in RubyUI element mapping (a→Link, button→Button, input→Input/Checkbox/RadioButton, table family, etc.) as fallbacks — Configuration does this by default (`ruby_ui: true`, CLI `--no-ruby-ui` to disable). `link_to`→`Link` happens separately in `rails_helpers.rb`, gated on `config.ruby_ui?`.
- **`rails_helpers.rb`** — translates `link_to`, `image_tag`, `render "partial"`, etc. into Phlex equivalents; `render` paths resolve to constants via `Naming.partial_const`. `link_to` targets that aren't strings or route helpers get wrapped in `url_for(...)`. Unmapped HTML helpers and object/collection `render` are emitted as **bare calls** — phlex-rails registers these as output helpers that write to the buffer themselves; only the string-returning helpers in `STRING_HELPERS` (`sanitize`, `safe_join`, `raw`, `strip_tags`) are wrapped via `transformer.config.raw_call`. Cross-file coupling to know about: `HTML_HELPERS`/`KNOWN_HELPERS` also serve as the LocalsDetector's exclusion list — adding a helper name there changes partial locals detection.
- **`form_builder.rb`** — translates Rails form-builder field calls (`form.text_field :name`, ...) inside a `form_with`/`form_for` block into RubyUI form components (`Input`/`Textarea`/`Checkbox`/`FormFieldLabel`/`Button`, and `collection_select` into a `NativeSelect` wrapping a `NativeSelectOption` loop), reconstructing `name`/`id` as `"model[attr]"` and `value` as `model.attr.to_s` (`.to_s` because Phlex rejects non-string/number attribute values like a `decimal`/BigDecimal column), and appending a `FormFieldError { model.errors[:attr].to_sentence.upcase_first }` after each input/textarea/checkbox. The Transformer pushes a form scope (`{var:, model:, param:}`) onto `@form_stack` while emitting a model-bound form block (`emit_form_control`, `current_form`), drops the `|form|` block var when every call maps, and routes `<%= form.* %>` outputs through `FormBuilder.transform` (and `special_output?` so they aren't inlined). Only active when `ruby_ui?` and a model is determinable; otherwise calls stay as-is. Heuristic — checkbox loses Rails' hidden field; bindings need review.
- **`locals_detector.rb`** — heuristic detection used by `Template`. `#locals` finds a partial's bare locals (→ initializer + private `attr_reader`s); excludes Ruby keywords plus the `RailsHelpers` constants above. `#ivars` finds the controller `@ivars` a top-level view reads (→ initializer that assigns them directly, no readers); excludes ivars assigned in the template and class variables.
- **`template.rb`** — per-file orchestrator: derives class name/namespace from the path (via `naming.rb`), parses, and renders the full class (frozen-string header, module nesting, initializer, `view_template`). `init_args` unifies the initializer's keyword args: a partial's detected `locals` (referenced via `attr_reader`s) or a top-level view's referenced `ivars` (assigned directly, no readers). With `literal: true`, those same names emit `prop :x, _Nilable(X)/_Any?` (Literal::Properties) instead of initialize/attr_reader.
- **Literal mode rewriting** — all emitted Ruby code funnels through `Transformer#sanitize_code`, which (in literal mode) rewrites bare local references to `@ivar`s via a Ripper token-level pass (`rewrite_locals_to_ivars`). This is safe because LocalsDetector only reports read-only names (anything assigned or used as a block param anywhere in the template is excluded) — that invariant is what makes blanket rewriting correct. Only partials need this: top-level views already reference `@ivars`, so `literal_locals` is empty for them and nothing is rewritten.
- **`converter.rb`** + **`file_walker.rb`** — directory-level orchestration; returns `Converter::Result` structs with `status` of `:written/:previewed/:skipped/:error`. Never overwrites existing `.rb` files unless `force`. `Converter#root` anchors namespace derivation (and `--output` mirroring) at the nearest `app/views` ancestor when present — so `convert app/views/users` still yields `Views::Users::*` — falling back to the converted folder; `config.root` overrides both.
- **`converter.rb`** + **`file_walker.rb`** — directory-level orchestration; returns `Converter::Result` structs with `status` of `:written/:previewed/:skipped/:error`. Never overwrites existing `.rb` files unless `force`. Two templates mapping to the same output in one run (`show.html.erb` + `show.html.haml`, `+variant`s) → the later one is an `:error` (checked before rendering). `Converter#root` anchors namespace derivation (and `--output` mirroring) at the nearest `app/views` ancestor when present — so `convert app/views/users` still yields `Views::Users::*` — falling back to the converted folder; `config.root` overrides both.
- **`configuration.rb`** — single options object threaded through everything. `phlex_version` decides the template method name (`view_template` for 2, `template` for 1) and the raw-output form via `raw_call` (`raw(safe(...))` for 2, `unsafe_raw(...)` for 1). `ruby_ui: true` (the default) installs the RubyUI fallback rules **in the constructor** — setting `config.ruby_ui = true` after construction does nothing; pass it as a kwarg.
- **`cli.rb`** — Thor CLI (`exe/ruby_ui_converter`); maps flags onto a `Configuration`. After each run it consults `Doctor` and (interactively) offers to install missing prerequisites.
- **`doctor.rb`** — post-conversion diagnostics: walks up from the converted path to the nearest Gemfile (`app_root`), then checks gems (phlex-rails/ruby_ui/literal), `extend Literal::Properties` on the base class, and which RubyUI generator families the emitted code references (`COMPONENT_FAMILIES` maps e.g. `TableCell`→`Table`) vs `app/components/ruby_ui/*`. Pure diagnosis — `Issue` structs carry shell `commands` (strings starting with `#` are manual hints, never executed) and an optional `fixer` proc; the CLI prompts and executes.

Entry points: `RubyUIConverter.convert(path, **opts)` (files) and `RubyUIConverter.convert_string(erb, ...)` (no IO — useful in tests).
Entry points: `RubyUIConverter.convert(path, **opts)` (files) and `RubyUIConverter.convert_string(source, format: :erb | :haml, ...)` (no IO — useful in tests).

## Testing notes

Expand All @@ -55,3 +61,6 @@ Entry points: `RubyUIConverter.convert(path, **opts)` (files) and `RubyUIConvert
- The default config maps elements/`link_to` to RubyUI kit calls (`Link(...)`, `Button(...)`) — tests asserting plain Phlex output (`a(...)`, `input(...)`) must pass `ruby_ui: false`.
- The suite checks generated files are valid Ruby syntax (`ruby -c`) — semantic equivalence is explicitly out of scope (the README documents the known limitations: heuristic locals, `form_with` blocks, `render @collection`/object forms emit a bare `render ...` call (phlex-rails handles it), raw `<script>/<style>` content wrapped via `Configuration#raw_call` — `raw(safe(...))` on Phlex 2, `unsafe_raw(...)` on Phlex 1).
- Minitest randomizes test order by default; the `rake test` task runs `test/**/*_test.rb`.
- `haml` is a **development** dependency (gemspec), so HAML tests (`haml_*_test.rb`, parts of `converter_test.rb`/`cli_test.rb`) can rely on it. Without a committed lockfile, CI resolves haml 6 on Ruby 3.0/3.1 and haml 7 on 3.2+, covering both interpolation shapes; to check haml 5.2/6 locally, run the tests under a throwaway Gemfile pinning that version (`BUNDLE_GEMFILE=... bundle exec ruby -Ilib -Itest ...`). Simulate a missing haml with `HamlParser.stub(:require_haml, -> { raise LoadError })` (`minitest/mock`).
- CLI tests (`cli_test.rb`) must pass `--dry-run` so the prerequisite check never prompts or installs.
- The E2E script also scaffolds a `Supplier` with haml-rails (`--template-engine=haml`, since tailwindcss-rails registers its own engine) and renders its converted HAML views.
Loading
Loading