herb 0.10.4 → 0.11.0

data/lib/herb/fingerprint.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+# typed: true
+
+require "digest"
+
+module Herb
+  # Identifies content by what it is instead of by where it lives or when it was touched.
+  #
+  #     Herb::Fingerprint.file(asset)      #=> "9f2a1c4e…"
+  #     Herb::Fingerprint.template(source) #=> "d242d277…"
+  #
+  module Fingerprint
+    BOM = "\xEF\xBB\xBF".b #: String
+    SHORT_LENGTH = 8 #: Integer
+
+    #: (String?) -> String?
+    def self.of(content)
+      return nil unless content
+
+      ::Digest::SHA256.hexdigest(content.to_s.b)
+    end
+
+    #: ((String | Pathname)?) -> String?
+    def self.file(path)
+      return nil unless path
+
+      ::Digest::SHA256.file(path.to_s).hexdigest
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    #: (String?) -> String?
+    def self.template(source)
+      return nil unless source
+
+      of(strip_bom(source.to_s.b))
+    end
+
+    #: ((String | Pathname)?) -> String?
+    def self.template_file(path)
+      return nil unless path
+
+      stat = File.stat(path.to_s)
+      key = [path.to_s, stat.mtime.to_i, stat.size]
+      cached = cache[key]
+
+      return cached if cached
+
+      digest = template(File.binread(path.to_s))
+
+      return nil unless digest
+
+      cache[key] = digest
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    #: (String?) -> String?
+    def self.short(digest)
+      digest&.slice(0, SHORT_LENGTH)
+    end
+
+    #: () -> void
+    def self.clear_cache
+      cache.clear
+
+      nil
+    end
+
+    #: () -> Hash[Array[untyped], String]
+    def self.cache
+      @cache ||= {} #: Hash[Array[untyped], String]
+    end
+
+    #: (String) -> String
+    def self.strip_bom(bytes)
+      return bytes unless bytes.start_with?(BOM)
+
+      bytes.byteslice(BOM.bytesize, bytes.bytesize - BOM.bytesize) || ""
+    end
+  end
+end

data/lib/herb/html/elements.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/html/elements.rb.erb
+
+module Herb
+  module HTML
+    module Elements
+      RAW_TEXT_ELEMENTS = ["script", "style", "iframe", "xmp", "noembed", "noframes", "plaintext"].freeze #: Array[String]
+      RCDATA_ELEMENTS = ["textarea", "title"].freeze #: Array[String]
+      VOID_ELEMENTS = ["area", "base", "basefont", "bgsound", "br", "col", "embed", "frame", "hr", "img", "input", "keygen", "link", "meta", "param", "source", "track", "wbr"].freeze #: Array[String]
+      BOOLEAN_ATTRIBUTES = ["allowfullscreen", "async", "autofocus", "autoplay", "checked", "compact", "controls", "declare", "default", "defer", "disabled", "formnovalidate", "hidden", "inert", "ismap", "itemscope", "loop", "multiple", "muted", "nomodule", "nohref", "noresize", "noshade", "novalidate", "nowrap", "open", "playsinline", "readonly", "required", "reversed", "scoped", "seamless", "selected", "sortable", "truespeed", "typemustmatch"].freeze #: Array[String]
+      WHITESPACE_PRESERVING_ELEMENTS = ["iframe", "listing", "noembed", "noframes", "plaintext", "pre", "script", "style", "textarea", "xmp"].freeze #: Array[String]
+      INLINE_ELEMENTS = ["a", "abbr", "acronym", "b", "bdo", "big", "br", "button", "cite", "code", "del", "dfn", "em", "hr", "i", "img", "input", "ins", "kbd", "label", "map", "mark", "object", "output", "q", "s", "samp", "select", "small", "span", "strong", "sub", "sup", "textarea", "time", "tt", "u", "var", "wbr"].freeze #: Array[String]
+    end
+  end
+end

data/lib/herb/html/util.rb

@@ -1,16 +1,35 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
+require_relative "elements"
+
 module Herb
   module HTML
     module Util
-      # TODO: extract to shared utility for all languages in .yml
-      VOID_ELEMENTS = ["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"].freeze #: Array[String]
+      VOID_ELEMENTS = Elements::VOID_ELEMENTS #: Array[String]
+      RCDATA_ELEMENTS = Elements::RCDATA_ELEMENTS #: Array[String]
+      RAW_TEXT_ELEMENTS = Elements::RAW_TEXT_ELEMENTS #: Array[String]
+      BOOLEAN_ATTRIBUTES = Elements::BOOLEAN_ATTRIBUTES #: Array[String]
 
       #: (String) -> bool
       def self.void_element?(tag_name)
         VOID_ELEMENTS.include?(tag_name.downcase)
       end
+
+      #: (String) -> bool
+      def self.rcdata_element?(tag_name)
+        RCDATA_ELEMENTS.include?(tag_name.downcase)
+      end
+
+      #: (String) -> bool
+      def self.raw_text_element?(tag_name)
+        RAW_TEXT_ELEMENTS.include?(tag_name.downcase)
+      end
+
+      #: (String) -> bool
+      def self.boolean_attribute?(attribute_name)
+        BOOLEAN_ATTRIBUTES.include?(attribute_name.downcase)
+      end
     end
   end
 end

data/lib/herb/lex_result.rb

@@ -10,15 +10,5 @@ module Herb
       @value = TokenList.new(value)
       super(source, warnings, errors)
     end
-
-    #: () -> bool
-    def success?
-      errors.empty?
-    end
-
-    #: () -> bool
-    def failed?
-      errors.any?
-    end
   end
 end

data/lib/herb/locate.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  # Finds the most specific node at a position, and the nodes it sits inside.
+  #
+  #     result = document.locate(Herb::Position.from(2, 7))
+  #
+  #     result.node      #=> the innermost node whose location contains the position
+  #     result.ancestors #=> every node it sits inside, nearest first
+  #
+  # A node and a parse result both answer, so a walk starts from whichever one a caller already
+  # holds. `Herb::AST::Node#locate` and `Herb::ParseResult#locate` are the same walk from different
+  # starting points.
+  #
+  # Everything that reads a position back from a rendered page, an editor, or a diagnostic needs
+  # this, and every caller was writing its own descent. A finding at `2:7` is a node before it is
+  # anything a person can act on.
+  #
+  # `ancestors` reads nearest first, the way `caller` does, so the enclosing element a caller wants
+  # is the first one that answers:
+  #
+  #     result.ancestors.find { |node| node.is_a?(Herb::AST::HTMLElementNode) }
+  #
+  # A node's location contains its start and stops short of its end, so two nodes sitting next to
+  # each other never both answer for the character between them. A position past the end of the
+  # source belongs to no node, and the answer is `nil`.
+  #
+  # Columns are 0-based character offsets into their line, which is what the parser reports.
+  # `Herb::Position#to_one_based` is what turns one into what an editor shows.
+  #
+  # `Herb::Locate::Result` holds what was found, and what it was found inside.
+  #
+  #     result.node      #=> #<Herb::AST::LiteralNode>
+  #     result.ancestors #=> [#<...HTMLAttributeNameNode>, #<...HTMLAttributeNode>, ...]
+  #
+  class Locate
+    class Result
+      attr_reader :node #: Herb::AST::Node
+      attr_reader :ancestors #: Array[Herb::AST::Node]
+
+      #: (Herb::AST::Node, Array[Herb::AST::Node]) -> void
+      def initialize(node, ancestors)
+        @node = node
+        @ancestors = ancestors
+
+        freeze
+      end
+
+      #: (untyped) -> Herb::AST::Node?
+      def innermost(kind)
+        return node if node.is_a?(kind)
+
+        ancestors.find { |ancestor| ancestor.is_a?(kind) } #: Herb::AST::Node?
+      end
+
+      #: () -> Array[Herb::AST::Node]
+      def path
+        ancestors.reverse + [node]
+      end
+
+      #: () -> String
+      def inspect
+        %(#<Herb::Locate::Result node=#{node.class} ancestors=#{ancestors.size}>)
+      end
+    end
+
+    #: ((Herb::AST::Node | Herb::ParseResult), Herb::Position) -> Result?
+    def self.call(node, position)
+      new(position).call(node)
+    end
+
+    #: ((Herb::AST::Node | Herb::ParseResult), Herb::Position) -> bool
+    def self.locatable?(node, position)
+      new(position).locatable?(node)
+    end
+
+    #: ((Herb::AST::Node | Herb::ParseResult)) -> Herb::AST::Node
+    def self.root(node)
+      node.is_a?(Herb::ParseResult) ? node.value : node
+    end
+
+    #: (Herb::Position) -> void
+    def initialize(position)
+      @position = position
+      @ancestors = [] #: Array[Herb::AST::Node]
+      extents = {} #: Hash[Herb::AST::Node, Herb::Location?]
+
+      @extents = extents.compare_by_identity
+    end
+
+    #: ((Herb::AST::Node | Herb::ParseResult)) -> Result?
+    def call(node)
+      root = self.class.root(node)
+
+      return nil unless within_extent?(root)
+
+      descend(root, [])
+    end
+
+    #: ((Herb::AST::Node | Herb::ParseResult)) -> bool
+    def locatable?(node)
+      within_extent?(self.class.root(node))
+    end
+
+    private
+
+    #: (Herb::AST::Node, Array[Herb::AST::Node]) -> Result?
+    def descend(node, ancestors)
+      child = node.compact_child_nodes.find { |candidate| within_extent?(candidate) }
+
+      return descend(child, [node] + ancestors) if child
+      return Result.new(node, ancestors) if contains?(node)
+
+      nearest = ancestors.index { |ancestor| contains?(ancestor) }
+
+      return nil unless nearest
+
+      Result.new(ancestors[nearest], ancestors.drop(nearest + 1))
+    end
+
+    #: (Herb::AST::Node) -> bool
+    def contains?(node)
+      location = node.location
+
+      return false unless location
+      return false if location.empty?
+
+      location.contains?(@position)
+    end
+
+    #: (Herb::AST::Node) -> bool
+    def within_extent?(node)
+      extent = extent(node)
+
+      !extent.nil? && extent.contains?(@position)
+    end
+
+    #: (Herb::AST::Node) -> Herb::Location?
+    def extent(node)
+      return @extents[node] if @extents.key?(node)
+
+      @extents[node] = nil
+
+      own = node.location
+      own = nil if own.nil? || own.empty?
+
+      extent = node.compact_child_nodes.filter_map { |child| extent(child) }.reduce(own) { |a, b| union(a, b) }
+
+      @extents[node] = extent
+    end
+
+    #: (Herb::Location?, Herb::Location) -> Herb::Location
+    def union(first, second)
+      return second unless first
+
+      Herb::Location.new(
+        [first.start, second.start].min, #: Herb::Position
+        [first.end, second.end].max #: Herb::Position
+      )
+    end
+  end
+end

data/lib/herb/location.rb

@@ -29,6 +29,26 @@ module Herb
       from(start_line, start_column, end_line, end_column)
     end
 
+    #: () -> Location
+    def self.zero
+      new(Position.zero, Position.zero)
+    end
+
+    #: (Position) -> bool
+    def contains?(position)
+      position >= start && position < self.end
+    end
+
+    #: (Location) -> bool
+    def covers?(other)
+      start <= other.start && other.end <= self.end
+    end
+
+    #: () -> bool
+    def empty?
+      start == self.end
+    end
+
     #: () -> serialized_location
     def to_hash
       {

data/lib/herb/parse_result.rb

@@ -3,15 +3,19 @@
 
 require "json"
 
+require_relative "locate"
+
 module Herb
   class ParseResult < Result
     attr_reader :value #: Herb::AST::DocumentNode
     attr_reader :options #: Herb::ParserOptions
+    attr_reader :error_count #: Integer?
 
-    #: (Herb::AST::DocumentNode, String, Array[Herb::Warnings::Warning], Array[Herb::Errors::Error], Herb::ParserOptions) -> void
-    def initialize(value, source, warnings, errors, options)
+    #: (Herb::AST::DocumentNode, String, Array[Herb::Warnings::Warning], Array[Herb::Errors::Error], Herb::ParserOptions, ?Integer?) -> void
+    def initialize(value, source, warnings, errors, options, error_count = nil)
       @value = value
       @options = options
+      @error_count = error_count
       super(source, warnings, errors)
 
       if options.prism_nodes || options.prism_nodes_deep
@@ -24,22 +28,24 @@ module Herb
 
     #: () -> Array[Herb::Errors::Error]
     def errors
+      return super if error_count&.zero?
+
       super + value.recursive_errors
     end
 
-    #: () -> bool
-    def failed?
-      errors.any?
+    #: () -> String
+    def pretty_errors
+      JSON.pretty_generate(errors)
     end
 
-    #: () -> bool
-    def success?
-      !failed?
+    #: (Herb::Position) -> Herb::Locate::Result?
+    def locate(position)
+      Locate.call(self, position)
     end
 
-    #: () -> String
-    def pretty_errors
-      JSON.pretty_generate(errors)
+    #: (Herb::Position) -> bool
+    def locatable?(position)
+      Locate.locatable?(self, position)
     end
 
     #: (Visitor) -> void

data/lib/herb/parser_options.rb

@@ -1,82 +1,101 @@
 # frozen_string_literal: true
+# typed: true
+
+# NOTE: This file is generated by the templates/template.rb script and should not be
+# modified manually. See templates/lib/herb/parser_options.rb.erb
 
 module Herb
   class ParserOptions
-    attr_reader :strict #: bool
-    attr_reader :track_whitespace #: bool
-    attr_reader :analyze #: bool
     attr_reader :action_view_helpers #: bool
-    attr_reader :transform_conditionals #: bool
-    attr_reader :render_nodes #: bool
-    attr_reader :strict_locals #: bool
-    attr_reader :prism_program #: bool
+    attr_reader :analyze #: bool
+    attr_reader :arena_stats #: bool
+    attr_reader :dot_notation_tags #: bool
+    attr_reader :erb_openers #: Array[String]
+    attr_reader :herb_directives #: bool
+    attr_reader :html #: bool
+    attr_reader :iteration_nodes #: bool
+    attr_reader :max_errors #: Integer?
     attr_reader :prism_nodes #: bool
     attr_reader :prism_nodes_deep #: bool
+    attr_reader :prism_program #: bool
+    attr_reader :render_nodes #: bool
+    attr_reader :strict #: bool
+    attr_reader :strict_locals #: bool
     attr_reader :timeout #: Numeric
-    attr_reader :max_errors #: Integer?
+    attr_reader :track_locations #: bool
+    attr_reader :track_whitespace #: bool
+    attr_reader :transform_conditionals #: bool
 
-    DEFAULT_STRICT = true #: bool
-    DEFAULT_TRACK_WHITESPACE = false #: bool
-    DEFAULT_ANALYZE = true #: bool
     DEFAULT_ACTION_VIEW_HELPERS = false #: bool
-    DEFAULT_TRANSFORM_CONDITIONALS = false #: bool
-    DEFAULT_RENDER_NODES = false #: bool
-    DEFAULT_STRICT_LOCALS = false #: bool
-    DEFAULT_PRISM_PROGRAM = false #: bool
+    DEFAULT_ANALYZE = true #: bool
+    DEFAULT_CAPTURE_ARENA_STATS = false #: bool
+    DEFAULT_DOT_NOTATION_TAGS = false #: bool
+    DEFAULT_HERB_DIRECTIVES = false #: bool
+    DEFAULT_HTML = true #: bool
+    DEFAULT_ITERATION_NODES = false #: bool
+    DEFAULT_MAX_ERRORS = 25 #: Integer
     DEFAULT_PRISM_NODES = false #: bool
     DEFAULT_PRISM_NODES_DEEP = false #: bool
+    DEFAULT_PRISM_PROGRAM = false #: bool
+    DEFAULT_RENDER_NODES = false #: bool
+    DEFAULT_STRICT = true #: bool
+    DEFAULT_STRICT_LOCALS = false #: bool
     DEFAULT_TIMEOUT = 1 #: Numeric
-    DEFAULT_MAX_ERRORS = 25 #: Integer
+    DEFAULT_TRACK_LOCATIONS = true #: bool
+    DEFAULT_TRACK_WHITESPACE = false #: bool
+    DEFAULT_TRANSFORM_CONDITIONALS = false #: bool
 
-    #: (?strict: bool, ?track_whitespace: bool, ?analyze: bool, ?action_view_helpers: bool, ?transform_conditionals: bool, ?render_nodes: bool, ?strict_locals: bool, ?prism_nodes: bool, ?prism_nodes_deep: bool, ?prism_program: bool, ?timeout: Numeric) -> void
-    def initialize(strict: DEFAULT_STRICT, track_whitespace: DEFAULT_TRACK_WHITESPACE, analyze: DEFAULT_ANALYZE, action_view_helpers: DEFAULT_ACTION_VIEW_HELPERS, transform_conditionals: DEFAULT_TRANSFORM_CONDITIONALS, render_nodes: DEFAULT_RENDER_NODES, strict_locals: DEFAULT_STRICT_LOCALS, prism_nodes: DEFAULT_PRISM_NODES, prism_nodes_deep: DEFAULT_PRISM_NODES_DEEP, prism_program: DEFAULT_PRISM_PROGRAM, timeout: DEFAULT_TIMEOUT, max_errors: DEFAULT_MAX_ERRORS)
-      @strict = strict
-      @track_whitespace = track_whitespace
-      @analyze = analyze
+    #: (?action_view_helpers: bool, ?analyze: bool, ?arena_stats: bool, ?dot_notation_tags: bool, ?erb_openers: Array[String], ?herb_directives: bool, ?html: bool, ?iteration_nodes: bool, ?max_errors: Integer?, ?prism_nodes: bool, ?prism_nodes_deep: bool, ?prism_program: bool, ?render_nodes: bool, ?strict: bool, ?strict_locals: bool, ?timeout: Numeric, ?track_locations: bool, ?track_whitespace: bool, ?transform_conditionals: bool) -> void
+    def initialize(action_view_helpers: DEFAULT_ACTION_VIEW_HELPERS, analyze: DEFAULT_ANALYZE, arena_stats: DEFAULT_CAPTURE_ARENA_STATS, dot_notation_tags: DEFAULT_DOT_NOTATION_TAGS, erb_openers: [], herb_directives: DEFAULT_HERB_DIRECTIVES, html: DEFAULT_HTML, iteration_nodes: DEFAULT_ITERATION_NODES, max_errors: DEFAULT_MAX_ERRORS, prism_nodes: DEFAULT_PRISM_NODES, prism_nodes_deep: DEFAULT_PRISM_NODES_DEEP, prism_program: DEFAULT_PRISM_PROGRAM, render_nodes: DEFAULT_RENDER_NODES, strict: DEFAULT_STRICT, strict_locals: DEFAULT_STRICT_LOCALS, timeout: DEFAULT_TIMEOUT, track_locations: DEFAULT_TRACK_LOCATIONS, track_whitespace: DEFAULT_TRACK_WHITESPACE, transform_conditionals: DEFAULT_TRANSFORM_CONDITIONALS)
       @action_view_helpers = action_view_helpers
-      @transform_conditionals = transform_conditionals
-      @render_nodes = render_nodes
-      @strict_locals = strict_locals
+      @analyze = analyze
+      @arena_stats = arena_stats
+      @dot_notation_tags = dot_notation_tags
+      @erb_openers = erb_openers
+      @herb_directives = herb_directives
+      @html = html
+      @iteration_nodes = iteration_nodes
+      @max_errors = max_errors
       @prism_nodes = prism_nodes
       @prism_nodes_deep = prism_nodes_deep
       @prism_program = prism_program
+      @render_nodes = render_nodes
+      @strict = strict
+      @strict_locals = strict_locals
       @timeout = timeout
-      @max_errors = max_errors
+      @track_locations = track_locations
+      @track_whitespace = track_whitespace
+      @transform_conditionals = transform_conditionals
     end
 
-    #: () -> Hash[Symbol, (bool | Numeric | nil)]
+    #: () -> Hash[Symbol, (bool | Numeric | Array[String] | nil)]
     def to_h
       {
-        strict: @strict,
-        track_whitespace: @track_whitespace,
-        analyze: @analyze,
         action_view_helpers: @action_view_helpers,
-        transform_conditionals: @transform_conditionals,
-        render_nodes: @render_nodes,
-        strict_locals: @strict_locals,
+        analyze: @analyze,
+        arena_stats: @arena_stats,
+        dot_notation_tags: @dot_notation_tags,
+        erb_openers: @erb_openers,
+        herb_directives: @herb_directives,
+        html: @html,
+        iteration_nodes: @iteration_nodes,
+        max_errors: @max_errors,
         prism_nodes: @prism_nodes,
         prism_nodes_deep: @prism_nodes_deep,
         prism_program: @prism_program,
+        render_nodes: @render_nodes,
+        strict: @strict,
+        strict_locals: @strict_locals,
         timeout: @timeout,
-        max_errors: @max_errors,
+        track_locations: @track_locations,
+        track_whitespace: @track_whitespace,
+        transform_conditionals: @transform_conditionals,
       }
     end
 
     #: () -> String
     def inspect
-      "#<#{self.class.name}\n  " \
-        "strict=#{@strict}\n  " \
-        "track_whitespace=#{@track_whitespace}\n  " \
-        "analyze=#{@analyze}\n  " \
-        "action_view_helpers=#{@action_view_helpers}\n  " \
-        "transform_conditionals=#{@transform_conditionals}\n  " \
-        "render_nodes=#{@render_nodes}\n  " \
-        "strict_locals=#{@strict_locals}\n  " \
-        "prism_nodes=#{@prism_nodes}\n  " \
-        "prism_nodes_deep=#{@prism_nodes_deep}\n  " \
-        "prism_program=#{@prism_program}\n  " \
-        "timeout=#{@timeout}\n  " \
-        "max_errors=#{@max_errors}>"
+      "#<#{self.class.name} #{to_h.map { |key, value| "#{key}=#{value.inspect}" }.join(", ")}>"
     end
   end
 end

data/lib/herb/position.rb

@@ -4,6 +4,8 @@
 module Herb
   #: type serialized_position = { line: Integer, column: Integer }
   class Position
+    include Comparable
+
     attr_reader :line #: Integer
     attr_reader :column #: Integer
 
@@ -23,11 +25,28 @@ module Herb
       new(line, column)
     end
 
+    #: () -> Position
+    def self.zero
+      new(0, 0)
+    end
+
+    #: (untyped) -> Integer?
+    def <=>(other)
+      return nil unless other.is_a?(Position)
+
+      [line, column] <=> [other.line, other.column]
+    end
+
     #: () -> serialized_position
     def to_hash
       { line: line, column: column } #: Herb::serialized_position
     end
 
+    #: () -> serialized_position
+    def to_one_based
+      { line: [line, 1].max, column: column + 1 } #: Herb::serialized_position
+    end
+
     #: (?untyped) -> String
     def to_json(state = nil)
       to_hash.to_json(state)

data/lib/herb/prism_inspect.rb

@@ -110,10 +110,7 @@ module Herb
 
       #: (Prism::Location) -> String
       def format_location(location)
-        start_line = location.start_line + 1
-        end_line = location.end_line + 1
-
-        "(#{start_line}:#{location.start_column})-(#{end_line}:#{location.end_column})"
+        "(#{location.start_line}:#{location.start_column})-(#{location.end_line}:#{location.end_column})"
       end
     end
   end