ruby_ui_converter 0.1.0

data/lib/ruby_ui_converter/cli.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module RubyUIConverter
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "convert PATH", "Convert .erb views/partials under PATH into RubyUI/Phlex .rb files"
+    long_desc <<~DESC
+      Recursively walks PATH looking for *.erb files and writes an equivalent
+      .rb component next to each one (e.g. index.html.erb -> index.rb). Rails
+      partials (_form.html.erb) become their own component classes (form.rb).
+
+      By default, basic HTML elements are mapped onto RubyUI kit components
+      (a -> Link, button -> Button, input -> Input, table -> Table, ...).
+      Pass --no-ruby-ui to emit plain Phlex elements instead.
+    DESC
+    option :namespace, default: "Views", desc: "Base module namespace for generated constants"
+    option :root, desc: "Directory namespaces are derived from (default: nearest app/views ancestor, else PATH)"
+    option :base_class, default: "Phlex::HTML", desc: "Superclass for generated components"
+    option :phlex, default: "2", desc: "Target Phlex major version (2 => view_template, 1 => template)"
+    option :output, aliases: "-o", desc: "Write into this directory instead of in place (mirrors structure)"
+    option :dry_run, type: :boolean, default: false, desc: "Print what would be generated without writing"
+    option :force, type: :boolean, default: false, desc: "Overwrite existing .rb files"
+    option :ruby_ui, type: :boolean, default: true, desc: "Map basic HTML elements onto RubyUI components (--no-ruby-ui for plain Phlex)"
+    option :literal, type: :boolean, default: false, desc: "Emit Literal::Properties props instead of initialize/attr_reader (requires the literal gem)"
+    option :verbose, type: :boolean, default: false
+    def convert(path)
+      unless File.exist?(path)
+        say "Path not found: #{path}", :red
+        exit 1
+      end
+
+      if options[:root]
+        root = File.expand_path(options[:root])
+        unless File.directory?(root) && File.expand_path(path).start_with?(root)
+          say "Invalid --root: #{options[:root]} (must be an existing ancestor of PATH)", :red
+          exit 1
+        end
+      end
+
+      config = Configuration.new(
+        base_namespace: options[:namespace],
+        root: options[:root],
+        base_class: options[:base_class],
+        phlex_version: options[:phlex],
+        output_root: options[:output],
+        dry_run: options[:dry_run],
+        force: options[:force],
+        ruby_ui: options[:ruby_ui],
+        literal: options[:literal],
+        verbose: options[:verbose]
+      )
+
+      results = Converter.new(path, config: config).run
+      report(results, config)
+      check_prerequisites(results, config, path)
+    end
+
+    desc "version", "Print the ruby_ui_converter version"
+    def version
+      say RubyUIConverter::VERSION
+    end
+
+    map %w[--version -v] => :version
+
+    private
+
+    def report(results, config)
+      if results.empty?
+        say "No .erb files found.", :yellow
+        return
+      end
+
+      results.each do |result|
+        case result.status
+        when :written
+          say "  created  #{relative(result.output)}", :green
+          preview(result) if config.verbose
+        when :previewed
+          say "  preview  #{relative(result.output)}", :cyan
+          preview(result)
+        when :skipped
+          say "  skipped  #{relative(result.output)} (exists, use --force)", :yellow
+        when :error
+          say "  error    #{relative(result.source)}: #{result.error.message}", :red
+        end
+      end
+
+      counts = results.group_by(&:status).transform_values(&:size)
+      say ""
+      say "Done. #{counts.map { |status, n| "#{n} #{status}" }.join(", ")}."
+    end
+
+    def preview(result)
+      return unless result.code
+
+      say "", nil
+      say result.code, :white
+      say "", nil
+    end
+
+    # Diagnoses the target app for the prerequisites the generated code needs
+    # (gems, RubyUI components, Literal::Properties) and offers to install
+    # them. Only warns in non-interactive sessions and on --dry-run.
+    def check_prerequisites(results, config, path)
+      doctor = Doctor.new(results, config: config, start_path: path)
+      issues = doctor.issues
+      return if issues.empty?
+
+      say ""
+      say "Missing prerequisites detected:", :yellow
+      issues.each { |issue| say "  - #{issue.description}", :yellow }
+
+      if config.dry_run || !$stdin.tty?
+        pending_commands(issues)
+        return
+      end
+
+      # Default to yes: only an explicit "n"/"no" skips; a bare Enter installs.
+      if no?("Install now? [Y/n]")
+        pending_commands(issues)
+        return
+      end
+
+      apply_fixes(issues, doctor.app_root)
+
+      # Some problems only appear after installing (e.g. ruby_ui:install
+      # leaving a broken tw-animate-css import, or the base class to extend
+      # Literal::Properties being created by phlex:install). One follow-up
+      # diagnosis catches and fixes those under the same consent.
+      follow_up = Doctor.new(results, config: config, start_path: path).issues
+      return if follow_up.empty?
+
+      say ""
+      say "Applying follow-up fixes:", :yellow
+      follow_up.each { |issue| say "  - #{issue.description}", :yellow }
+      apply_fixes(follow_up, doctor.app_root)
+    end
+
+    def apply_fixes(issues, app_root)
+      issues.each { |issue| issue.fixer&.call }
+      run_commands(issues.flat_map { |issue| issue.commands || [] }, app_root)
+    end
+
+    def pending_commands(issues)
+      say ""
+      say "To fix, run:", :yellow
+      issues.flat_map { |issue| issue.commands || [] }.each { |cmd| say "  #{cmd}", :yellow }
+    end
+
+    def run_commands(commands, app_root)
+      commands.reject { |cmd| cmd.start_with?("#") }.each do |cmd|
+        say "  running #{cmd}", :cyan
+        unless run_in_app(cmd, app_root)
+          say "  command failed: #{cmd} — run it manually.", :red
+          break
+        end
+      end
+    end
+
+    def run_in_app(cmd, app_root)
+      if defined?(Bundler)
+        Bundler.with_unbundled_env { system(cmd, chdir: app_root) }
+      else
+        system(cmd, chdir: app_root)
+      end
+    end
+
+    def relative(path)
+      return path unless path
+
+      path.delete_prefix("#{Dir.pwd}/")
+    end
+  end
+end

data/lib/ruby_ui_converter/code_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyUIConverter
+  # Accumulates indented lines of Ruby source.
+  class CodeBuilder
+    def initialize(indent: "  ", level: 0)
+      @indent = indent
+      @level = level
+      @lines = []
+    end
+
+    attr_reader :level
+
+    def line(str = nil)
+      @lines << (str.nil? || str.empty? ? "" : (@indent * @level) + str)
+      self
+    end
+
+    def indent
+      @level += 1
+      self
+    end
+
+    def dedent
+      @level -= 1 if @level.positive?
+      self
+    end
+
+    def to_s
+      "#{@lines.join("\n")}\n"
+    end
+  end
+end

data/lib/ruby_ui_converter/component_map.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module RubyUIConverter
+  # Maps HTML elements onto RubyUI (or any Phlex) components.
+  #
+  # Two layers of rules:
+  #   * user rules, added with #register — always win;
+  #   * fallback rules — the built-in RubyUI element mapping installed by
+  #     Configuration when `ruby_ui` is enabled (the default).
+  #
+  # Each rule has:
+  #   * matcher: ->(Nodes::Element) { Boolean }
+  #   * emitter: ->(Nodes::Element, Transformer, CodeBuilder) { ... }
+  #
+  # The emitter is responsible for writing the component call. It can use the
+  # transformer's public helpers (kit_component, wrap_component, emit_children,
+  # render_attrs, meaningful).
+  #
+  # Example of a custom rule (overrides the built-in `button` mapping):
+  #
+  #   config.component_map.register(
+  #     ->(el) { el.name == "button" && el.static_classes.include?("danger") }
+  #   ) do |el, transformer, builder|
+  #     transformer.kit_component("Button", el, builder, extra: "variant: :destructive")
+  #   end
+  class ComponentMap
+    Rule = Struct.new(:matcher, :emitter)
+
+    # Element name -> [RubyUI kit component, void?] for 1:1 mappings.
+    ELEMENT_COMPONENTS = {
+      "button" => ["Button", false],
+      "textarea" => ["Textarea", false],
+      "select" => ["NativeSelect", false],
+      "option" => ["NativeSelectOption", false],
+      "table" => ["Table", false],
+      "thead" => ["TableHeader", false],
+      "tbody" => ["TableBody", false],
+      "tfoot" => ["TableFooter", false],
+      "tr" => ["TableRow", false],
+      "th" => ["TableHead", false],
+      "td" => ["TableCell", false],
+      "caption" => ["TableCaption", false],
+      "hr" => ["Separator", true]
+    }.freeze
+
+    def initialize
+      @rules = []
+      @fallback_rules = []
+    end
+
+    def register(matcher, &emitter)
+      @rules << Rule.new(matcher, emitter)
+      self
+    end
+
+    def register_fallback(matcher, &emitter)
+      @fallback_rules << Rule.new(matcher, emitter)
+      self
+    end
+
+    # @return [Proc, nil] the emitter for the first matching rule.
+    # User rules take precedence over the built-in fallback rules.
+    def lookup(node)
+      rule = @rules.find { |r| r.matcher.call(node) } ||
+             @fallback_rules.find { |r| r.matcher.call(node) }
+      rule&.emitter
+    end
+
+    def empty?
+      @rules.empty? && @fallback_rules.empty?
+    end
+
+    # Built-in mapping of basic HTML elements onto RubyUI kit components
+    # (Link, Button, Input, ...). Installed as fallback rules so user rules
+    # registered with #register always win.
+    def self.rubyui_rules(map)
+      # <a href=...> -> Link(href: ...). Anchors without href stay plain.
+      map.register_fallback(->(el) { el.name == "a" && el.attr?("href") }) do |el, t, b|
+        t.kit_component("Link", el, b)
+      end
+
+      # <input> -> Checkbox / RadioButton / Input, dispatched on a static
+      # type attribute (Checkbox and RadioButton set their own type).
+      map.register_fallback(->(el) { el.name == "input" }) do |el, t, b|
+        case el.static_attr("type")
+        when "checkbox" then t.kit_component("Checkbox", el, b, except: ["type"], void: true)
+        when "radio" then t.kit_component("RadioButton", el, b, except: ["type"], void: true)
+        else t.kit_component("Input", el, b, void: true)
+        end
+      end
+
+      ELEMENT_COMPONENTS.each do |element, (component, void)|
+        map.register_fallback(->(el) { el.name == element }) do |el, t, b|
+          t.kit_component(component, el, b, void: void)
+        end
+      end
+
+      # Rails flash paragraphs (<p id="notice">/<p id="alert">) -> RubyUI Alert.
+      # `notice` is a success message; `alert` is an error (destructive).
+      map.register_fallback(->(el) { el.name == "p" && %w[notice alert].include?(el.static_attr("id")) }) do |el, t, b|
+        kind = el.static_attr("id")
+        variant = kind == "alert" ? "destructive" : "success"
+        # mb-5 keeps the alert from sitting flush against the content below it
+        # (the scaffold's flash <p> had mb-5, dropped when we replace the tag).
+        b.line(%(Alert(variant: :#{variant}, class: "mb-5") do))
+        b.indent
+        b.line(%(AlertTitle { "#{kind.capitalize}" }))
+        t.component_block("AlertDescription", el.children, b)
+        b.dedent
+        b.line("end")
+      end
+
+      # Class-based heuristics for common Bootstrap-ish markup.
+      map.register_fallback(->(el) { el.static_classes.include?("badge") }) do |el, t, b|
+        t.kit_component("Badge", el, b)
+      end
+
+      map.register_fallback(->(el) { el.static_classes.include?("card") }) do |el, t, b|
+        t.kit_component("Card", el, b)
+      end
+
+      map
+    end
+  end
+end

data/lib/ruby_ui_converter/configuration.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyUIConverter
+  class Configuration
+    attr_accessor :base_namespace, :base_class, :phlex_version, :indent,
+                  :output_root, :verbose, :dry_run, :force, :ruby_ui,
+                  :literal, :root, :component_map
+
+    def initialize(base_namespace: "Views", base_class: "Phlex::HTML",
+                   phlex_version: 2, indent: "  ", output_root: nil,
+                   verbose: false, dry_run: false, force: false, ruby_ui: true,
+                   literal: false, root: nil)
+      @base_namespace = base_namespace
+      @base_class = base_class
+      @phlex_version = phlex_version
+      @indent = indent
+      @output_root = output_root
+      @verbose = verbose
+      @dry_run = dry_run
+      @force = force
+      @ruby_ui = ruby_ui
+      @literal = literal
+      @root = root
+      @component_map = ComponentMap.new
+      enable_rubyui_rules! if ruby_ui
+    end
+
+    # Phlex 2 uses `view_template`; Phlex 1 used `template`.
+    def template_method
+      phlex_version.to_i >= 2 ? "view_template" : "template"
+    end
+
+    # Emit a raw (unescaped) output call for the given Ruby expression. Phlex 2
+    # dropped `unsafe_raw` in favor of `raw(safe(...))`; Phlex 1 used
+    # `unsafe_raw(...)`.
+    def raw_call(expr)
+      phlex_version.to_i >= 2 ? "raw(safe(#{expr}))" : "unsafe_raw(#{expr})"
+    end
+
+    def ruby_ui?
+      !!@ruby_ui
+    end
+
+    def literal?
+      !!@literal
+    end
+
+    def enable_rubyui_rules!
+      ComponentMap.rubyui_rules(@component_map)
+      self
+    end
+  end
+end

data/lib/ruby_ui_converter/converter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module RubyUIConverter
+  # Orchestrates the conversion of an entire directory (or single file).
+  class Converter
+    Result = Struct.new(:source, :output, :status, :error, :code, keyword_init: true)
+
+    def initialize(path, config: Configuration.new)
+      @path = path
+      @config = config
+    end
+
+    # The namespace root. Precedence: explicit config.root, then the nearest
+    # `app/views` ancestor (Rails convention — keeps generated constants
+    # matching the Zeitwerk path mapping no matter which subfolder was
+    # converted), then the directory the user pointed at.
+    def root
+      @root ||=
+        if @config.root
+          File.expand_path(@config.root)
+        else
+          base =
+            if File.directory?(@path)
+              File.expand_path(@path)
+            else
+              File.dirname(File.expand_path(@path))
+            end
+          conventional_root(base) || base
+        end
+    end
+
+    def run
+      FileWalker.new(@path).erb_files.map { |file| convert_file(file) }
+    end
+
+    private
+
+    # Nearest ancestor (including dir itself) that is a Rails `app/views`
+    # directory, or nil when the path is not inside one.
+    def conventional_root(dir)
+      current = dir
+      loop do
+        return current if File.basename(current) == "views" &&
+                          File.basename(File.dirname(current)) == "app"
+
+        parent = File.dirname(current)
+        return nil if parent == current
+
+        current = parent
+      end
+    end
+
+    def convert_file(file)
+      file = File.expand_path(file)
+      template = Template.new(path: file, root: root, config: @config)
+      code = template.render
+      output = template.output_path
+
+      if @config.dry_run
+        return Result.new(source: file, output: output, status: :previewed, code: code)
+      end
+
+      if File.exist?(output) && !@config.force
+        return Result.new(source: file, output: output, status: :skipped, code: code)
+      end
+
+      FileUtils.mkdir_p(File.dirname(output))
+      File.write(output, code)
+      Result.new(source: file, output: output, status: :written, code: code)
+    rescue StandardError => e
+      Result.new(source: file, output: nil, status: :error, error: e)
+    end
+  end
+end

data/lib/ruby_ui_converter/doctor.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module RubyUIConverter
+  # Post-conversion diagnostics: inspects the target app (the nearest Gemfile
+  # at or above the converted path) for the prerequisites the generated code
+  # needs — phlex-rails, the ruby_ui gem + generated components and, with
+  # --literal, the literal gem + Literal::Properties on the base class.
+  #
+  # The Doctor only diagnoses; executing the fix commands (and prompting the
+  # user) is the CLI's responsibility. Commands starting with "#" are manual
+  # hints, not executable; issues may also carry a `fixer` proc that applies
+  # a file edit (e.g. inserting `extend Literal::Properties`).
+  class Doctor
+    Issue = Struct.new(:description, :commands, :fixer, keyword_init: true)
+
+    # Emitted kit component -> `ruby_ui:component` generator family.
+    COMPONENT_FAMILIES = {
+      "Link" => "Link", "Button" => "Button", "Input" => "Input",
+      "Checkbox" => "Checkbox", "RadioButton" => "RadioButton",
+      "Textarea" => "Textarea",
+      "NativeSelect" => "NativeSelect", "NativeSelectOption" => "NativeSelect",
+      "Table" => "Table", "TableHeader" => "Table", "TableBody" => "Table",
+      "TableFooter" => "Table", "TableRow" => "Table", "TableHead" => "Table",
+      "TableCell" => "Table", "TableCaption" => "Table",
+      "Separator" => "Separator", "Badge" => "Badge", "Card" => "Card",
+      "FormField" => "Form", "FormFieldLabel" => "Form",
+      "FormFieldError" => "Form", "FormFieldHint" => "Form",
+      "Alert" => "Alert", "AlertTitle" => "Alert", "AlertDescription" => "Alert"
+    }.freeze
+
+    def initialize(results, config:, start_path:)
+      @results = results
+      @config = config
+      @start_path = File.expand_path(start_path)
+    end
+
+    # The nearest directory at or above start_path containing a Gemfile.
+    # nil when the converted path is not inside a bundled app.
+    def app_root
+      return @app_root if defined?(@app_root)
+
+      dir = File.directory?(@start_path) ? @start_path : File.dirname(@start_path)
+      @app_root = loop do
+        break dir if File.exist?(File.join(dir, "Gemfile"))
+
+        parent = File.dirname(dir)
+        break nil if parent == dir
+
+        dir = parent
+      end
+    end
+
+    def issues
+      return [] unless app_root
+
+      [
+        phlex_rails_issue,
+        literal_gem_issue,
+        literal_properties_issue,
+        ruby_ui_gem_issue,
+        missing_components_issue,
+        tw_animate_issue
+      ].compact
+    end
+
+    private
+
+    def gemfile
+      @gemfile ||= File.read(File.join(app_root, "Gemfile"))
+    end
+
+    def gem?(name)
+      gemfile.match?(/^\s*gem\s+["']#{Regexp.escape(name)}["']/)
+    end
+
+    def phlex_rails_issue
+      return if gem?("phlex-rails")
+
+      Issue.new(
+        description: %(gem "phlex-rails" not in Gemfile (required by the generated Phlex classes)),
+        commands: ["bundle add phlex-rails", "bin/rails generate phlex:install"]
+      )
+    end
+
+    def literal_gem_issue
+      return unless @config.literal?
+      return if gem?("literal")
+
+      Issue.new(
+        description: %(gem "literal" not in Gemfile (required by --literal props)),
+        commands: ["bundle add literal"]
+      )
+    end
+
+    def literal_properties_issue
+      return unless @config.literal?
+
+      base = base_component_file
+      if base.nil?
+        return Issue.new(
+          description: "no base component class found to extend Literal::Properties",
+          commands: ["# add `extend Literal::Properties` to your base component class"]
+        )
+      end
+      return if File.read(base).include?("Literal::Properties")
+
+      rel = base.delete_prefix("#{app_root}/")
+      Issue.new(
+        description: "Literal::Properties not extended in #{rel}",
+        commands: ["# add `extend Literal::Properties` to #{rel} (auto-applied on install)"],
+        fixer: lambda do
+          content = File.read(base)
+          updated = content.sub(/^(\s*class\s+\S+\s*<\s*\S+.*)$/) do
+            "#{Regexp.last_match(1)}\n  extend Literal::Properties"
+          end
+          File.write(base, updated) unless updated == content
+        end
+      )
+    end
+
+    def base_component_file
+      ["app/components/base.rb", "app/views/base.rb"]
+        .map { |rel| File.join(app_root, rel) }
+        .find { |path| File.exist?(path) }
+    end
+
+    def ruby_ui_gem_issue
+      return unless @config.ruby_ui? && emitted_families.any?
+      return if gem?("ruby_ui")
+
+      Issue.new(
+        description: %(gem "ruby_ui" not in Gemfile (the generated code calls RubyUI components)),
+        commands: ["bundle add ruby_ui", "bin/rails generate ruby_ui:install"]
+      )
+    end
+
+    def missing_components_issue
+      return unless @config.ruby_ui?
+
+      missing = emitted_families.reject { |family| component_installed?(family) }
+      return if missing.empty?
+
+      Issue.new(
+        description: "RubyUI components not generated: #{missing.join(", ")}",
+        # ruby_ui:component takes a single component per invocation, so emit one
+        # command per missing component rather than a single multi-arg call.
+        commands: missing.map { |family| "bin/rails generate ruby_ui:component #{family}" }
+      )
+    end
+
+    # Which generator families the converted code actually references.
+    def emitted_families
+      @emitted_families ||= begin
+        code = @results.map(&:code).compact.join("\n")
+        COMPONENT_FAMILIES.select { |name, _| code.match?(/\b#{name}\(/) }
+                          .values.uniq
+      end
+    end
+
+    def component_installed?(family)
+      snake = family.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      File.directory?(File.join(app_root, "app/components/ruby_ui", snake))
+    end
+
+    TW_ANIMATE_URL = "https://cdn.jsdelivr.net/npm/tw-animate-css/dist/tw-animate.css"
+    TW_ANIMATE_IMPORT = /@import\s+["'][^"']*tw-animate-css\.js["'];?/
+
+    # `ruby_ui:install` pins tw-animate-css via importmap, but the package is
+    # CSS-only and the pin fails on jspm — leaving application.css importing a
+    # vendor file that was never downloaded (breaks tailwindcss:build/bin/dev).
+    # Fix: vendor the real CSS next to application.css and point the import
+    # at it.
+    def tw_animate_issue
+      css_path = File.join(app_root, "app/assets/tailwind/application.css")
+      return unless File.exist?(css_path)
+      return unless File.read(css_path).match?(TW_ANIMATE_IMPORT)
+      return if File.exist?(File.join(app_root, "vendor/javascript/tw-animate-css.js"))
+
+      Issue.new(
+        description: "broken tw-animate-css import in app/assets/tailwind/application.css " \
+                     "(the importmap pin from ruby_ui:install failed)",
+        commands: ["curl -fsSL -o app/assets/tailwind/tw-animate.css #{TW_ANIMATE_URL}"],
+        fixer: lambda do
+          content = File.read(css_path)
+          File.write(css_path, content.sub(TW_ANIMATE_IMPORT, %(@import "./tw-animate.css";)))
+        end
+      )
+    end
+  end
+end

data/lib/ruby_ui_converter/file_walker.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyUIConverter
+  # Finds .erb files under a path (recursively for directories).
+  class FileWalker
+    ERB_GLOB = "**/*.erb"
+
+    def initialize(path)
+      @path = path
+    end
+
+    def erb_files
+      if File.directory?(@path)
+        Dir.glob(File.join(@path, ERB_GLOB)).select { |f| File.file?(f) }.sort
+      elsif File.file?(@path) && @path.end_with?(".erb")
+        [@path]
+      else
+        []
+      end
+    end
+  end
+end