herbst 0.0.1 → 0.1.0

data/lib/herbst/cli.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Herbst
+  # The `herbst` command.
+  #
+  #   herbst convert app/views/posts/show.html.haml   # prints the ERB
+  #   herbst convert app/views                        # writes show.html.erb next to show.html.haml or .slim
+  #
+  # A single file is printed to stdout unless `--write` is given. Directories and multiple
+  # files are written next to their sources, replacing the `.haml` or `.slim` extension with `.erb`.
+  # Existing ERB files are skipped unless `--force` is given. A file without a format gets
+  # `html`, so `show.haml` becomes `show.html.erb`, while `welcome.text.haml` keeps its format.
+  #
+  class CLI
+    class Conversion
+      attr_reader :path #: String
+      attr_reader :warnings #: Array[String]
+      attr_reader :error #: String?
+      attr_reader :difference #: String?
+      attr_accessor :erb #: String?
+
+      #: (String, ?erb: String?, ?warnings: Array[String], ?error: String?, ?difference: String?) -> void
+      def initialize(path, erb: nil, warnings: [], error: nil, difference: nil)
+        @path = path
+        @erb = erb
+        @warnings = warnings
+        @error = error
+        @difference = difference
+      end
+
+      #: () -> bool
+      def failed?
+        !error.nil? || !difference.nil?
+      end
+    end
+
+    # @rbs @arguments: Array[String]
+    # @rbs @stdout: IO
+    # @rbs @stderr: IO
+    # @rbs @format: bool
+    # @rbs @verify: bool
+    # @rbs @write: bool
+    # @rbs @force: bool
+    # @rbs @default_format: String?
+    # @rbs @help: bool
+    # @rbs @version: bool
+    # @rbs @option_parser: OptionParser?
+
+    #: (Array[String], ?stdout: IO, ?stderr: IO) -> void
+    def initialize(arguments, stdout: $stdout, stderr: $stderr)
+      @arguments = arguments
+      @stdout = stdout
+      @stderr = stderr
+      @format = true
+      @verify = true
+      @write = false
+      @force = false
+      @default_format = "html"
+      @help = false
+      @version = false
+    end
+
+    #: () -> Integer
+    def run
+      command, *paths = option_parser.parse(@arguments)
+
+      return help if @help
+      return version if @version
+
+      case command
+      when "convert"
+        paths.empty? ? help(1, "Missing path: pass the Haml or Slim files, or directories, to convert.") : convert(paths)
+      when "help"
+        help
+      when "version"
+        version
+      when String
+        help(1, "Unknown command: '#{command}'")
+      else
+        help(1)
+      end
+    rescue OptionParser::ParseError => e
+      help(1, e.message)
+    end
+
+    private
+
+    #: (Array[String]) -> Integer
+    def convert(paths)
+      missing = paths.reject { |path| File.exist?(path) }
+      return fail_with("#{missing.join(", ")}: No such file or directory") unless missing.empty?
+
+      files = paths.flat_map { |path| File.directory?(path) ? Dir[File.join(path, "**", "*.{haml,slim}")] : [path] }.sort
+      return fail_with("No .haml or .slim files found in #{paths.join(", ")}") if files.empty?
+
+      conversions = files.map { |file| convert_file(file) }
+      format(conversions) if @format
+
+      write = @write || paths.size > 1 || paths.any? { |path| File.directory?(path) }
+      write ? write_files(conversions) : print_file(conversions.fetch(0))
+    end
+
+    #: () -> OptionParser
+    def option_parser
+      @option_parser ||= OptionParser.new do |parser|
+        parser.banner = ""
+
+        parser.on_tail("-v", "--version", "Show the version") { @version = true }
+        parser.on_tail("-h", "--help", "Show this message") { @help = true }
+
+        parser.on("--force", "Overwrite existing ERB files (for convert command)") { @force = true }
+        parser.on("--no-format", "Don't run the Herb formatter on the output (for convert command)") { @format = false }
+
+        parser.on("--no-verify", "Don't check the ERB parses back into the converted tree (for convert command)") do
+          @verify = false
+        end
+
+        parser.on("--write", "Write a single file next to its source instead of printing it (for convert command)") do
+          @write = true
+        end
+
+        parser.on("--default-format FORMAT", "Format for files without one (default: html) (for convert command)") do |format|
+          @default_format = format
+        end
+
+        parser.on("--no-default-format", "Don't add a format to files without one, as in show.erb (for convert command)") do
+          @default_format = nil
+        end
+      end
+    end
+
+    #: (?Integer, ?String?) -> Integer
+    def help(exit_code = 0, message = nil)
+      io = exit_code.zero? ? @stdout : @stderr
+
+      io.puts message, "" if message
+      io.puts <<~HELP
+        Herbst 🍂 Unified syntax tree for HTML templating languages.
+
+        Usage:
+          bundle exec herbst [command] [options]
+
+        Commands:
+          bundle exec herbst convert [paths]    Convert Haml and Slim files, or every one in a directory, to ERB.
+          bundle exec herbst help               Show this message.
+          bundle exec herbst version            Prints the versions of Herbst, Herb, Haml and Slim.
+
+        Converting:
+          A single file is printed to stdout, unless `--write` is passed:
+            bundle exec herbst convert app/views/posts/show.html.haml
+
+          Directories, and several files at once, are written next to their sources:
+            bundle exec herbst convert app/views
+
+          Existing ERB files are skipped unless `--force` is passed. The Haml and Slim files are kept.
+
+          A file without a format gets html, so show.haml becomes show.html.erb. Pass
+          `--default-format FORMAT` for another format, or `--no-default-format` to write show.erb.
+
+        Options:
+      HELP
+      io.puts option_parser.to_s.delete_prefix("\n").gsub(/^    /, "  "), ""
+
+      exit_code
+    end
+
+    #: () -> Integer
+    def version
+      versions = ["herbst gem v#{VERSION}", "herb gem v#{Herb::VERSION}"]
+
+      ["haml", "slim"].each do |name|
+        version = Gem::Specification.find_all_by_name(name).map(&:version).max # steep:ignore
+        versions << "#{name} gem v#{version}" if version
+      end
+
+      @stdout.puts versions.join(", ")
+
+      0
+    end
+
+    #: (String) -> Conversion
+    def convert_file(file)
+      converter = converter_for(file)
+      document = converter.convert(File.read(file, encoding: "UTF-8"))
+      erb = IdentityPrinter.print(document)
+      difference = RoundTrip.difference(document, erb) if @verify
+
+      Conversion.new(file, erb: erb, warnings: converter.warnings, difference: difference)
+    rescue Herbst::Error => e
+      Conversion.new(file, error: e.message)
+    end
+
+    #: (String) -> Herbst::Converter
+    def converter_for(path)
+      File.extname(path) == ".slim" ? Slim::Converter.new : Haml::Converter.new
+    end
+
+    #: (Array[Conversion]) -> void
+    def format(conversions)
+      converted = conversions.select(&:erb)
+      formatted = Printer.format_all(converted.map { |conversion| conversion.erb.to_s })
+
+      converted.zip(formatted) { |conversion, erb| conversion.erb = erb }
+    end
+
+    #: (Conversion) -> Integer
+    def print_file(conversion)
+      report(conversion)
+      @stdout.print(conversion.erb) if conversion.erb
+
+      conversion.failed? ? 1 : 0
+    end
+
+    #: (Array[Conversion]) -> Integer
+    def write_files(conversions)
+      written = 0
+      skipped = 0
+
+      conversions.each do |conversion|
+        report(conversion)
+
+        erb = conversion.erb
+        next unless erb
+
+        target = target_path(conversion.path)
+
+        if File.exist?(target) && !@force
+          @stderr.puts "#{conversion.path}: #{target} already exists, skipped (use --force to overwrite)"
+          skipped += 1
+        else
+          File.write(target, erb)
+          written += 1
+        end
+      end
+
+      failed = conversions.count(&:failed?)
+      @stderr.puts summary(conversions.size, written, skipped, failed)
+
+      failed.positive? ? 1 : 0
+    end
+
+    #: (String) -> String
+    def target_path(path)
+      base = path.sub(/\.(haml|slim)\z/, "")
+      base = "#{base}.#{@default_format}" if @default_format && !File.basename(base).include?(".")
+
+      "#{base}.erb"
+    end
+
+    #: (Conversion) -> void
+    def report(conversion)
+      conversion.warnings.each { |warning| @stderr.puts "#{conversion.path}: #{warning}" }
+      @stderr.puts "#{conversion.path}: #{conversion.error}" if conversion.error
+      @stderr.puts "#{conversion.path}: #{conversion.difference}" if conversion.difference
+    end
+
+    #: (Integer, Integer, Integer, Integer) -> String
+    def summary(total, written, skipped, failed)
+      parts = ["Converted #{written} of #{total} #{total == 1 ? "file" : "files"}"]
+
+      parts << "#{skipped} skipped" if skipped.positive?
+      parts << "#{failed} failed" if failed.positive?
+
+      "#{parts.join(", ")}."
+    end
+
+    #: (String) -> Integer
+    def fail_with(message)
+      @stderr.puts message
+
+      1
+    end
+  end
+end

data/lib/herbst/converter.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Herbst
+  class Converter
+    include Builder
+
+    INDENT = "  " #: String
+
+    # @rbs!
+    #   type clause = [String, String?, Array[Herb::AST::Node], Integer?]
+
+    attr_reader :warnings #: Array[String]
+
+    # @rbs @markup: bool
+
+    #: () -> void
+    def initialize
+      @warnings = []
+      @markup = false
+    end
+
+    #: (String) -> Herb::AST::DocumentNode
+    def convert(source)
+      raise NotImplementedError, "#{self.class} must implement `convert`"
+    end
+
+    #: (String) -> Array[Herb::AST::Node]
+    def text_nodes(value)
+      @markup = true if value.match?(%r{<[\p{L}/!?]})
+
+      value.split(/(<%|%>)/).reject(&:empty?).map do |part|
+        case part
+        when "<%"
+          erb('"<%"', opening: "<%==")
+        when "%>"
+          erb('"%\>"', opening: "<%==")
+        else
+          text(part)
+        end
+      end
+    end
+
+    #: (Integer?, String) -> void
+    def warn(line, message)
+      @warnings << (line ? "line #{line}: #{message}" : message)
+    end
+
+    private
+
+    #: (Herb::AST::DocumentNode) -> Herb::AST::DocumentNode
+    def finish(document)
+      document = merge_texts!(document)
+      return document unless @markup
+
+      Herb.parse(IdentityPrinter.print(document), track_whitespace: true).value
+    end
+
+    #: (Integer) -> String
+    def newline(depth)
+      "\n#{INDENT * depth}"
+    end
+
+    #: (String) -> String?
+    def keyword(code)
+      code[/\A\s*(if|unless|case|begin|while|until|for|elsif|else|when|in|rescue|ensure)\b/, 1]
+    end
+
+    #: (String, String?, Array[Herb::AST::Node], Array[clause], Integer, ?line: Integer?) -> Herb::AST::Node
+    def control(code, keyword, body, clauses, depth, line: nil)
+      case keyword
+      when "if"
+        control_if(code, body, clauses)
+      when "unless"
+        control_unless(code, body, clauses)
+      when "case"
+        control_case(code, body, clauses, depth, line)
+      when "begin"
+        control_begin(code, body, clauses)
+      when "while"
+        clauses.empty? ? erb_while(code, body) : control_block(code, body, clauses)
+      when "until"
+        clauses.empty? ? erb_until(code, body) : control_block(code, body, clauses)
+      when "for"
+        clauses.empty? ? erb_for(code, body) : control_block(code, body, clauses)
+      else
+        control_block(code, body, clauses)
+      end
+    end
+
+    #: (String, Array[Herb::AST::Node], Array[clause]) -> Herb::AST::ERBIfNode
+    def control_if(code, body, clauses)
+      subsequent = nil #: (Herb::AST::ERBIfNode | Herb::AST::ERBElseNode)?
+
+      clauses.reverse_each do |clause_code, clause_keyword, clause_body, clause_line|
+        subsequent =
+          case clause_keyword
+          when "else"
+            erb_else(clause_body)
+          when "elsif"
+            erb_if(clause_code, clause_body, subsequent: subsequent, end_node: nil)
+          else
+            unsupported_clause(clause_keyword, "if", clause_line)
+          end
+      end
+
+      erb_if(code, body, subsequent: subsequent)
+    end
+
+    #: (String, Array[Herb::AST::Node], Array[clause]) -> Herb::AST::ERBUnlessNode
+    def control_unless(code, body, clauses)
+      clauses.each do |_code, clause_keyword, _body, clause_line|
+        unsupported_clause(clause_keyword, "unless", clause_line) unless clause_keyword == "else"
+      end
+
+      else_clause = clauses.find { |clause| clause[1] == "else" }
+
+      erb_unless(code, body, else_clause: else_clause && erb_else(else_clause[2]))
+    end
+
+    #: (String, Array[Herb::AST::Node], Array[clause], Integer, Integer?) -> Herb::AST::ERBCaseNode
+    def control_case(code, body, clauses, depth, line)
+      unless body.all? { |node| node.is_a?(Herb::AST::HTMLTextNode) && node.content.to_s.strip.empty? }
+        warn(line, "content between `case` and the first `when` was dropped")
+      end
+
+      conditions = clauses.filter_map do |clause_code, clause_keyword, clause_body, clause_line|
+        case clause_keyword
+        when "when"
+          erb_when(clause_code, clause_body)
+        when "else"
+          nil
+        else
+          unsupported_clause(clause_keyword, "case", clause_line)
+        end
+      end
+
+      else_clause = clauses.find { |clause| clause[1] == "else" }
+      node = erb_case(code, conditions, else_clause: else_clause && erb_else(else_clause[2]))
+      first = conditions.first&.statements&.first
+
+      node.children << text(newline(depth)) if first.is_a?(Herb::AST::HTMLTextNode) && first.content.to_s.start_with?("\n")
+
+      node
+    end
+
+    #: (String, Array[Herb::AST::Node], Array[clause]) -> Herb::AST::ERBBeginNode
+    def control_begin(code, body, clauses)
+      else_clause = clauses.find { |clause| clause[1] == "else" }
+      ensure_clause = clauses.find { |clause| clause[1] == "ensure" }
+
+      rescue_clause = nil #: Herb::AST::ERBRescueNode?
+
+      clauses.select { |clause| clause[1] == "rescue" }.reverse_each do |clause_code, _keyword, clause_body, _line|
+        rescue_clause = erb_rescue(clause_code, clause_body, subsequent: rescue_clause)
+      end
+
+      erb_begin(
+        code, body,
+        rescue_clause: rescue_clause,
+        else_clause: else_clause && erb_else(else_clause[2]),
+        ensure_clause: ensure_clause && erb_ensure(ensure_clause[2])
+      )
+    end
+
+    #: (String, Array[Herb::AST::Node], Array[clause]) -> Herb::AST::ERBBlockNode
+    def control_block(code, body, clauses)
+      body = body.dup
+
+      clauses.each do |clause_code, _keyword, clause_body, _line|
+        body << erb(clause_code, opening: "<%")
+        body.concat(clause_body)
+      end
+
+      erb_block(code, body)
+    end
+
+    #: (String?, String, Integer?) -> bot
+    def unsupported_clause(clause_keyword, keyword, line)
+      raise Herbst::UnsupportedError.new("`#{clause_keyword}` is not supported inside `#{keyword}`", line)
+    end
+  end
+end

data/lib/herbst/haml/attributes.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require "temple"
+
+module Herbst
+  module Haml
+    class Attributes
+      include Builder
+
+      # @rbs @warnings: Array[String]
+
+      #: (Array[String]) -> void
+      def initialize(warnings)
+        @warnings = warnings
+      end
+
+      #: (::Haml::Parser::ParseNode) -> Array[Herb::AST::Node]
+      def compile(node)
+        value = node.value
+        dynamic = value[:dynamic_attributes]
+        sources = [dynamic.new, dynamic.old].compact
+
+        if value[:object_ref] != :nil
+          warn(node, "object references (`[#{value[:object_ref]}]`) are not supported and were dropped")
+        end
+
+        hashes = sources.filter_map { |source| ::Haml::AttributeParser.parse(source) }
+        return fallback(node, sources) if hashes.size < sources.size || hashes.any? { |hash| hash.any? { |_key, code| code.empty? } }
+
+        values = Hash.new { |hash, key| hash[key] = [] } #: Hash[String, Array[[Symbol, untyped]]]
+        value[:attributes].each { |key, static| values[key.to_s] << [:static, static] }
+        hashes.each { |hash| hash.each { |key, code| values[key.to_s] << [:dynamic, code] } }
+
+        values.keys.sort.flat_map { |key| compile_attribute(key, values[key]) }
+      end
+
+      private
+
+      #: (String, Array[[Symbol, untyped]]) -> Array[Herb::AST::Node]
+      def compile_attribute(key, values)
+        # Literal-only Ruby (checked by Temple::StaticAnalyzer) is folded into static values.
+        values = values.map do |type, value|
+          type == :dynamic && literal?(value) ? [:static, eval(value)] : [type, value] # rubocop:disable Security/Eval
+        end #: Array[[Symbol, untyped]]
+
+        case key
+        when "class"
+          compile_joined(key, values, " ") do |code|
+            array_literal?(code) ? "#{code}.flatten.select(&:itself).join(\" \")" : code
+          end
+        when "id"
+          compile_joined(key, values, "_") do |code|
+            array_literal?(code) ? "#{code}.flatten.select(&:itself).join(\"_\")" : code
+          end
+        when "data", "aria"
+          compile_hash(key, values.fetch(-1))
+        else
+          compile_single(key, values.fetch(-1))
+        end
+      end
+
+      #: (String, Array[[Symbol, untyped]], String) { (String) -> String } -> Array[Herb::AST::Node]
+      def compile_joined(key, values, separator)
+        statics = values.filter_map { |type, value| value if type == :static }
+        statics = statics.flat_map { |value| Array(value).flatten }.select(&:itself).map(&:to_s)
+        statics = statics.flat_map { |value| value.split(separator) } if separator == " "
+        dynamics = values.filter_map { |type, code| yield(code) if type == :dynamic }
+
+        return [] if statics.empty? && dynamics.empty?
+
+        children = [] #: Array[Herb::AST::Node]
+        children << literal(escape(statics.uniq.join(separator))) unless statics.empty?
+        dynamics.each do |code|
+          children << literal(separator) unless children.empty?
+          children << erb(code)
+        end
+
+        [attribute(key, children)]
+      end
+
+      #: (String, [Symbol, untyped]) -> Array[Herb::AST::Node]
+      def compile_hash(prefix, pair)
+        type, value = pair
+
+        hash = type == :static ? value : ::Haml::AttributeParser.parse(value)
+
+        unless hash.is_a?(Hash)
+          return compile_single(prefix, [type, value]) unless type == :dynamic
+
+          return [erb("tag.attributes(#{prefix}: #{value})")]
+        end
+
+        hash.sort_by { |key, _| key.to_s }.flat_map do |key, nested|
+          name = "#{prefix}-#{key.to_s.tr("_", "-")}"
+          nested_type = type == :static || literal?(nested) ? :static : :dynamic
+          nested_value = type == :dynamic && nested_type == :static ? eval(nested) : nested # rubocop:disable Security/Eval
+
+          if nested_value.is_a?(Hash) || (nested_type == :dynamic && ::Haml::AttributeParser.parse(nested).is_a?(Hash))
+            compile_hash(name, [nested_type, nested_value])
+          else
+            compile_single(name, [nested_type, nested_value])
+          end
+        end
+      end
+
+      #: (String, [Symbol, untyped]) -> Array[Herb::AST::Node]
+      def compile_single(key, pair)
+        type, value = pair
+
+        if type == :static
+          case value
+          when true
+            [attribute(key)]
+          when false, nil
+            []
+          else
+            [attribute(key, [literal(escape(value.to_s))])]
+          end
+        elsif boolean?(key)
+          [erb("#{key.inspect} if #{value}")]
+        else
+          [attribute(key, [erb(value)])]
+        end
+      end
+
+      #: (::Haml::Parser::ParseNode, Array[String]) -> Array[Herb::AST::Node]
+      def fallback(node, sources)
+        arguments = sources.map { |source| source.strip.delete_prefix("{").delete_suffix("}").strip.delete_suffix(",") }
+        warn(node, "dynamic attributes `#{sources.join(" ")}` were converted to `tag.attributes`, which requires Rails 7.1+")
+
+        node.value[:attributes].sort.flat_map { |key, value| compile_single(key, [:static, value]) } + [erb("tag.attributes(#{arguments.join(", ")})")]
+      end
+
+      #: (String) -> bool
+      def literal?(code)
+        Temple::StaticAnalyzer.static?(code)
+      end
+
+      #: (String) -> bool
+      def array_literal?(code)
+        code.strip.start_with?("[")
+      end
+
+      #: (String) -> bool
+      def boolean?(key)
+        ::Haml::BOOLEAN_ATTRIBUTES.include?(key)
+      end
+
+      #: (String) -> String
+      def escape(value)
+        CGI.escapeHTML(value).gsub("<%", "&lt;%")
+      end
+
+      #: (::Haml::Parser::ParseNode, String) -> void
+      def warn(node, message)
+        @warnings << "line #{node.line}: #{message}"
+      end
+    end
+  end
+end