herb 0.10.4 → 0.11.0

data/lib/herb/engine/slots/identifier.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Herb
+  class Engine
+    module Slots
+      # What a template is called on the wire. Markers, the values payload and the dependency map all
+      # name a template, and they only name the same one when they all follow this rule.
+      #
+      class Identifier
+        STRATEGIES = [:path, :digest].freeze #: Array[Symbol]
+
+        #: ((Symbol | ^(String) -> String)) -> void
+        def initialize(strategy = :path)
+          raise ArgumentError, "unknown identifier #{strategy.inspect}, expected one of #{STRATEGIES.inspect} or a callable" if strategy.is_a?(Symbol) && !STRATEGIES.include?(strategy)
+
+          @strategy = strategy
+        end
+
+        #: (String) -> String
+        def call(relative_path)
+          case @strategy
+          when :path
+            relative_path
+          when :digest
+            Digest::SHA256.hexdigest(relative_path).slice(0, 12).to_s
+          else
+            @strategy.call(relative_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/manifest/channel.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../../runtime/session"
+
+module Herb
+  class Engine
+    module Slots
+      module Manifest
+        # What every template on a page said about itself, collected once however many times those
+        # templates rendered.
+        #
+        # A template compiled with `deliver: :hoist` registers here as it renders:
+        #
+        #     ::Herb::Engine::Slots::Manifest::Channel.record("app/views/posts/_card.html.erb:a1b2c3d4", "{...}")
+        #
+        # It is a channel on the session the page is collecting into, so it registers itself the first
+        # time anything records, and nothing in `Report` or `Session` has to know it exists. A manifest
+        # is decided when a file is compiled, so the first template to record a version says everything
+        # there is to say about it and every later rendering costs nothing.
+        #
+        class Channel
+          NAME = :slot_manifest #: Symbol
+          ATTRIBUTE = "data-herb-manifests" #: String
+          ANCHOR = :body #: Symbol
+
+          #: (String, String) -> void
+          def self.record(key, json)
+            Runtime::Session.current.channel(NAME) { new }.add(key, json)
+
+            nil
+          end
+
+          #: () -> void
+          def initialize
+            @manifests = {} #: Hash[String, String]
+          end
+
+          #: (String, String) -> void
+          def add(key, json)
+            @manifests[key] ||= json
+
+            nil
+          end
+
+          #: () -> Hash[String, String]
+          def manifests
+            @manifests.dup
+          end
+
+          #: () -> Symbol
+          def anchor
+            ANCHOR
+          end
+
+          #: () -> bool
+          def empty?
+            @manifests.empty?
+          end
+
+          #: () -> String
+          def to_html
+            return "" if empty?
+
+            body = @manifests.map { |key, json| "#{JSON.generate(key)}:#{json}" }.join(",")
+
+            %(<template #{ATTRIBUTE} data-count="#{@manifests.size}">{#{body}}</template>)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/manifest/collector.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../../collector"
+require_relative "../visitor"
+
+module Herb
+  class Engine
+    module Slots
+      module Manifest
+        # What a set of templates says about itself, gathered without rendering any of them.
+        #
+        # A manifest is decided when a file is compiled, so everything a page needs to know about
+        # its templates is knowable ahead of time. This compiles each file for that and nothing
+        # else, which is what makes it possible to write the manifests into an asset and have
+        # templates carry none of them:
+        #
+        #     collector = Herb::Engine::Slots::Manifest::Collector.new(project_path: root)
+        #
+        #     collector.add("app/views/posts/_card.html.erb")
+        #     collector.add("app/views/posts/index.html.erb")
+        #
+        #     collector.to_json #=> the one file those templates add up to
+        #
+        # Which files to give it, and where the asset goes, is the job of whatever integrates Herb
+        # with a framework. This knows how to compile and what to keep.
+        #
+        class Collector < Engine::Collector
+          #: (?identifier: untyped?, ?project_path: (String | Pathname)?, **untyped) -> void
+          def initialize(identifier: nil, **)
+            super(**)
+
+            @identifier = identifier
+            @manifests = {} #: Hash[String, Hash[String, untyped]]
+          end
+
+          #: ((String | Pathname), ?String?) -> String?
+          def add(file, source = nil)
+            compile(file, source, Visitor.new(**{ mode: :client, mark: false, identifier: @identifier }.compact)) { |visitor|
+              manifest = visitor.manifest
+
+              next nil if manifest["names"].empty? && manifest["parts"].empty? && manifest["states"].nil? && manifest["bindings"].empty?
+
+              key = "#{visitor.identifier}:#{visitor.version}"
+              @manifests[key] ||= manifest
+
+              key
+            }
+          end
+
+          #: () -> Hash[String, Hash[String, untyped]]
+          def manifests
+            @manifests.dup
+          end
+
+          #: () -> bool
+          def empty?
+            @manifests.empty?
+          end
+
+          #: () -> String
+          def to_json(*)
+            JSON.generate(@manifests, script_safe: true)
+          end
+
+          #: () -> String
+          def inspect
+            "#<#{self.class.name} manifests=#{@manifests.size} failures=#{@failures.size}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/markers.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      class Markers
+        DEFAULT_TYPE = :child #: Symbol
+        ITEM_STATICS = "item" #: String
+        SEED_VALUE_TYPES = "[true, false, ::Integer, ::String, ::Symbol, nil]" #: String
+        PREFIX = "herb-" #: String
+        COMMENT = %r{\A<!--/?#{PREFIX}} #: Regexp
+
+        #: (String) -> bool
+        def self.marker?(text)
+          COMMENT.match?(text)
+        end
+
+        #: (String) -> String
+        def self.seeds_expression(pairs)
+          "{ #{pairs} }.select { |_, v| #{SEED_VALUE_TYPES}.any? { |t| t === v } }.transform_values { |v| v.is_a?(::Symbol) ? v.to_s : v }"
+        end
+
+        #: (Integer, Symbol) -> String
+        def slot_open(index, type)
+          return "<!--#{PREFIX}slot:#{index}-->" if type == DEFAULT_TYPE
+
+          "<!--#{PREFIX}slot:#{index}:#{type}-->"
+        end
+
+        #: (Array[[Integer, Symbol, String?]]) -> String
+        def element_anchors(anchors)
+          anchors.map { |index, type, name| name ? "#{index}:#{type}:#{name}" : "#{index}:#{type}" }.join(" ")
+        end
+
+        #: (Integer) -> String
+        def slot_close(index)
+          "<!--/#{PREFIX}slot:#{index}-->"
+        end
+
+        #: (Integer, Integer | String) -> String
+        def branch(slot_index, branch_index)
+          "<!--#{PREFIX}branch:#{slot_index}:#{branch_index}-->"
+        end
+
+        #: (Integer, Integer | String) -> String
+        def statics_key(slot_index, branch_index)
+          "#{slot_index}:#{branch_index}"
+        end
+
+        #: (Integer) -> String
+        def item_statics_key(slot_index)
+          statics_key(slot_index, ITEM_STATICS)
+        end
+
+        #: () -> String
+        def seeds_open_prefix
+          "<!--#{PREFIX}seeds:"
+        end
+
+        #: () -> String
+        def seeds_open_suffix
+          "-->"
+        end
+
+        #: (Integer) -> String
+        def keyed_open_prefix(slot_index)
+          "<!--#{PREFIX}slot:#{slot_index}:keyed:"
+        end
+
+        #: () -> String
+        def keyed_open_suffix
+          "-->"
+        end
+
+        #: (Integer) -> String
+        def item_open_prefix(slot_index)
+          "<!--#{PREFIX}item:#{slot_index}:"
+        end
+
+        #: () -> String
+        def item_open_suffix
+          "-->"
+        end
+
+        #: (Integer) -> String
+        def item_close(slot_index)
+          "<!--/#{PREFIX}item:#{slot_index}-->"
+        end
+
+        #: (String, String) -> String
+        def region_open_prefix(file, version)
+          "<!--#{PREFIX}region:#{file}:#{version}:"
+        end
+
+        #: () -> String
+        def region_open_suffix
+          "-->"
+        end
+
+        #: (String) -> String
+        def region_close(file)
+          "<!--/#{PREFIX}region:#{file}-->"
+        end
+
+        #: (String, String) -> String
+        def statics_open(file, version)
+          %(<template data-herb-region="#{file}:#{version}">)
+        end
+
+        #: () -> String
+        def statics_close
+          "</template>"
+        end
+
+        #: () -> String
+        def manifests_open
+          %(<template data-herb-manifests>)
+        end
+
+        #: () -> String
+        def manifests_close
+          "</template>"
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/render_bindings.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "state_kinds"
+
+module Herb
+  class Engine
+    module Slots
+      # Reads the `state:` entries off a render call and answers the call without them.
+      #
+      # The parser already took the hash apart into one declaration node per entry, with the
+      # kind it would give a `herb:state` default, so a value the parser calls bare is a
+      # candidate for a binding to one of the caller's states and anything else is a seed.
+      # The splice works on the argument's location, turned into an index into the tag's
+      # content, so the stripped call is the original source minus exactly the `state:`
+      # argument and the comma that carried it.
+      #
+      module RenderBindings
+        BARE_IDENTIFIER = /\A[a-z_][a-zA-Z0-9_]*\z/ #: Regexp
+        SPLAT = "**" #: String
+
+        REFUSED = {
+          float: "Ruby and JavaScript disagree on how to print a float, so the server and the client would render different text.",
+          array: "A list on the page is a collection of items, not one state holding many values.",
+          hash: "A state holds one value the client can write and read back.",
+        }.freeze #: Hash[Symbol, String]
+
+        Entry = Data.define(
+          :name,      #: String
+          :source,    #: String
+          :candidate, #: String?
+          :kind,      #: Symbol
+          :location   #: Herb::Location?
+        )
+
+        Analysis = Data.define(
+          :entries,  #: Array[Entry]
+          :stripped, #: String
+          :problems  #: Array[[String, String, Herb::Location?]]
+        )
+
+        #: (untyped) -> Analysis?
+        def self.analyze(node)
+          keywords = node.keywords
+          token = node.content
+          span = keywords&.state_location
+
+          return nil unless keywords && token && span
+
+          stripped = strip(token, span)
+
+          return nil unless stripped
+
+          entries = [] #: Array[Entry]
+          problems = [] #: Array[[String, String, Herb::Location?]]
+
+          keywords.state.each { |state| collect(state, entries, problems) }
+
+          Analysis.new(entries: entries, stripped: stripped, problems: problems)
+        end
+
+        #: (untyped, Array[Entry], Array[[String, String, Herb::Location?]]) -> void
+        def self.collect(state, entries, problems)
+          name = state.name&.value.to_s
+          location = state.location
+
+          if name.start_with?(SPLAT)
+            problems << ["`state:` spells every binding out as `name: value`, and `#{name}` hides which states it binds.", "Write the states out one by one.", location]
+
+            return
+          end
+
+          unless BARE_IDENTIFIER.match?(name)
+            problems << ["`#{name}` is not a state name.", "Name each state with a symbol key, like `open: modal_open`.", location]
+
+            return
+          end
+
+          if entries.any? { |entry| entry.name == name }
+            problems << ["`state:` binds `#{name}` twice.", "Keep one entry for `#{name}`.", location]
+
+            return
+          end
+
+          source = state.default_value&.content.to_s
+          bare = state.kind == "bare" && BARE_IDENTIFIER.match?(source)
+          refused = state.kind.to_s.to_sym
+
+          entries << Entry.new(
+            name: name,
+            source: source,
+            candidate: bare ? source : nil,
+            kind: StateKinds::NODE[state.kind] || (REFUSED.key?(refused) ? refused : :seeded),
+            location: location
+          )
+        end
+
+        #: (untyped, Herb::Location) -> String?
+        def self.strip(token, span)
+          value = token.value
+          from = index_in(token, span.start)
+          to = index_in(token, span.end)
+
+          return nil unless from && to && from <= to && to <= value.length
+
+          before = value[0...from].to_s
+          after = value[to..].to_s
+
+          if after.match?(/\A\s*,/)
+            after = after.sub(/\A\s*,\s*/, "")
+          else
+            before = before.sub(/\s*,\s*\z/, "")
+          end
+
+          before + after
+        end
+
+        #: (untyped, Herb::Position) -> Integer?
+        def self.index_in(token, position)
+          start = token.location&.start
+
+          return nil unless start
+          return nil if position.line < start.line
+
+          lines = token.value.lines
+          skipped = position.line - start.line
+
+          return nil if skipped > lines.length
+
+          column = skipped.zero? ? position.column - start.column : position.column
+
+          return nil if column.negative?
+
+          lines.first(skipped).sum(&:length) + column
+        end
+
+        private_class_method :collect, :strip, :index_in
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/schema_compiler.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "../../../herb"
+require_relative "../../engine"
+require_relative "visitor"
+
+module Herb
+  class Engine
+    module Slots
+      # Compiles a template into what a browser needs to know about its slots, without
+      # rendering anything.
+      #
+      # Slot identity depends on every visitor that runs before the slot visitor, and only
+      # the host knows its stack, so the host hands one over and this runs it. The stack
+      # arrives as a builder returning fresh visitors, because a visitor is stateful and the
+      # statics need a second compile:
+      #
+      #     result = Herb::Engine::Slots::SchemaCompiler.call(
+      #       source,
+      #       filename: "app/views/posts/index.html.erb",
+      #       mode: :client,
+      #       visitors: -> { [Herb::Engine::Validators::SecurityValidator.new(fatal: false)] }
+      #     )
+      #
+      #     result.version        #=> "5d1e0c77"
+      #     result.manifest       #=> what the page's manifest says
+      #     result.static_markup  #=> the markup with every slot as an empty marker pair
+      #
+      # A nil `mode` means slots are off for this template. The stack still runs so its
+      # diagnostics still flow, and everything slot-shaped comes back nil.
+      #
+      class SchemaCompiler
+        Result = Data.define(
+          :mode,          #: Symbol?
+          :manifest,      #: Hash[String, untyped]?
+          :version,       #: String?
+          :slot_entries,  #: Array[Hash[Symbol, untyped]]?
+          :statics,       #: Hash[String, String]?
+          :static_markup, #: String?
+          :diagnostics    #: Array[Herb::Diagnostic]
+        )
+
+        #: (String, filename: String, mode: Symbol?, ?visitors: ^() -> Array[::Herb::Visitor], ?engine: singleton(::Herb::Engine), ?options: Hash[Symbol, untyped]) -> Result
+        def self.call(source, filename:, mode:, visitors: -> { [] }, engine: Herb::Engine, options: {})
+          unless mode
+            stack = visitors.call
+
+            compile(engine, source, filename, stack, options)
+
+            return Result.new(
+              mode: nil,
+              manifest: nil,
+              version: nil,
+              slot_entries: nil,
+              statics: nil,
+              static_markup: nil,
+              diagnostics: collect(stack)
+            )
+          end
+
+          slot_visitor = Visitor.new(mode: mode, mark: false, deliver: :none, fatal: false)
+          stack = visitors.call + [slot_visitor]
+
+          compile(engine, source, filename, stack, options)
+
+          marking = Visitor.new(mode: mode, mark: true, deliver: :none, fatal: false, static_markup: true)
+
+          compile(engine, source, filename, visitors.call + [marking], options)
+
+          Result.new(
+            mode: mode,
+            manifest: slot_visitor.manifest,
+            version: slot_visitor.version,
+            slot_entries: slot_visitor.slot_entries,
+            statics: marking.statics,
+            static_markup: marking.static_markup,
+            diagnostics: collect(stack)
+          )
+        end
+
+        #: (singleton(::Herb::Engine), String, String, Array[::Herb::Visitor], Hash[Symbol, untyped]) -> void
+        def self.compile(engine, source, filename, stack, options)
+          engine.new(source, options.merge(filename: filename, visitors: stack))
+        end
+
+        #: (Array[::Herb::Visitor]) -> Array[Herb::Diagnostic]
+        def self.collect(stack)
+          stack.flat_map { |visitor| visitor.is_a?(Herb::Visitor::Diagnostics) ? visitor.diagnostics : [] }
+        end
+      end
+    end
+  end
+end

data/lib/herb/engine/slots/state_anchor.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Engine
+    module Slots
+      # Points a diagnostic at the part of an expression that is actually wrong.
+      #
+      # A condition reaches the state compiler as a string that was cut out of an ERB token, so a
+      # Prism node inside it knows only its own offset within that string. This carries the token
+      # the string came from and turns those offsets back into a location in the template. When it
+      # has nothing to work with it answers the whole node's location, which is what every
+      # diagnostic used before.
+      #
+      # A node resolved out of the template's whole Prism program counts from the start of the
+      # template instead, so `rebased` takes the offset those nodes count from.
+      #
+      class StateAnchor
+        attr_reader :location #: Herb::Location?
+
+        #: (Herb::Location?, ?token: Herb::Token?, ?expression: String?, ?context: Symbol, ?base: Integer) -> void
+        def initialize(location, token: nil, expression: nil, context: :condition, base: 0)
+          @location = location #: Herb::Location?
+          @token = token #: Herb::Token?
+          @expression = expression #: String?
+          @context = context #: Symbol
+          @base = base #: Integer
+        end
+
+        #: (Integer) -> StateAnchor
+        def rebased(base)
+          StateAnchor.new(@location, token: @token, expression: @expression, context: @context, base: base)
+        end
+
+        #: () -> bool
+        def condition?
+          @context == :condition
+        end
+
+        #: (::Prism::Node) -> Herb::Location?
+        def locate(node)
+          return location unless node.respond_to?(:location)
+
+          offset = character_offset(node)
+
+          return location unless offset
+
+          length = node.slice.to_s.length #: Integer
+
+          Herb::Location.new(advance(offset), advance(offset + length))
+        end
+
+        private
+
+        #: (::Prism::Node) -> Integer?
+        def character_offset(node)
+          token = @token
+          expression = @expression
+          start = @location&.start
+
+          return nil unless token && expression && start
+
+          source = token.value.to_s
+          within = source.index(expression)
+
+          return nil unless within
+
+          bytes = node.location.start_offset - @base
+
+          return nil if bytes.negative?
+
+          prefix = expression.byteslice(0, bytes)
+
+          return nil unless prefix
+
+          within + prefix.length
+        end
+
+        #: (Integer) -> Herb::Position
+        def advance(offset)
+          anchored = location || Herb::Location.zero
+          line = anchored.start.line
+          column = anchored.start.column
+          consumed = @token&.value.to_s[0, offset].to_s #: String
+          breaks = consumed.count("\n") #: Integer
+
+          return Herb::Position.new(line, column + consumed.length) if breaks.zero?
+
+          Herb::Position.new(line + breaks, consumed.length - consumed.rindex("\n").to_i - 1)
+        end
+      end
+    end
+  end
+end