diff --git a/CHANGELOG.md b/CHANGELOG.md index 0347af9..ae069b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 (`a <%= 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 diff --git a/CLAUDE.md b/CLAUDE.md index 7dddf0f..31be3ed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 @@ -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** (`RUCxERBxxERBxRUC`) 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 @@ -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 `