herb 0.10.4 → 0.11.0

data/sig/herb/engine/validators.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/herb/engine/validators.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # The validators Herb ships, and one way to ask for the ones a project has switched on.
+    #
+    # Nothing here runs unless a caller asks for it. `Herb::Engine` compiles whatever passes it is
+    # given and holds no opinion about validation, so wanting the usual set means saying so:
+    #
+    #     Herb::Engine.new(source, visitors: Herb::Engine::Validators.all(fatal: false))
+    #
+    # Reading which ones are switched on lives here rather than in the engine, so that a caller
+    # that already knows what it wants never has to consult configuration at all.
+    module Validators
+      ALL: Hash[Symbol, untyped]
+
+      # : (?fatal: bool, **untyped) -> Herb::Visitor::Stack
+      def self.all: (?fatal: bool, **untyped) -> Herb::Visitor::Stack
+    end
+  end
+end

data/sig/herb/engine/visitors/auto_close_omitted_tags_visitor.rbs

@@ -0,0 +1,26 @@
+# Generated from lib/herb/engine/visitors/auto_close_omitted_tags_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Replaces omitted closing tags with explicit ones, so that the compiled output always
+    # contains a closing tag, even when the template omits it.
+    #
+    # This visitor is not loaded by default. Require it explicitly and pass it to the engine:
+    #
+    #     require "herb/engine/visitors/auto_close_omitted_tags_visitor"
+    #
+    #     Herb::Engine.new(source, visitors: [Herb::Engine::AutoCloseOmittedTagsVisitor.new])
+    class AutoCloseOmittedTagsVisitor < Herb::Visitor
+      # : (Herb::AST::HTMLElementNode) -> void
+      def visit_html_element_node: (Herb::AST::HTMLElementNode) -> void
+
+      # : () -> String
+      def inspect: () -> String
+
+      private
+
+      # : (Herb::Token, Herb::Location) -> Herb::AST::HTMLCloseTagNode
+      def explicit_close_tag: (Herb::Token, Herb::Location) -> Herb::AST::HTMLCloseTagNode
+    end
+  end
+end

data/sig/herb/engine/visitors/content_for_visitor.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/herb/engine/visitors/content_for_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Appends HTML to the end of every element matching a tag name, and optionally a set of
+    # attribute conditions, so that the compiled output always contains it before the
+    # element's closing tag.
+    #
+    # An attribute condition matches on `true` when the attribute is present, on `false` when
+    # it is absent, on a `Regexp` when the attribute value matches it, and on anything else
+    # when the attribute value is equal to it. An attribute whose value is built from ERB has
+    # no value known at compile time, so it only matches the `true` condition.
+    #
+    # This visitor is not loaded by default. Require it explicitly and pass it to the engine:
+    #
+    #     require "herb/engine/visitors/content_for_visitor"
+    #
+    #     Herb::Engine.new(source, visitors: [
+    #       Herb::Engine::ContentForVisitor.new("<p>Footer</p>", tag_name: "main", attributes: { "id" => "content" })
+    #     ])
+    class ContentForVisitor < Herb::Visitor
+      # : (String?, tag_name: String, ?attributes: Hash[untyped, untyped]) -> void
+      def initialize: (String?, tag_name: String, ?attributes: Hash[untyped, untyped]) -> void
+
+      # : (Herb::AST::HTMLElementNode) -> void
+      def visit_html_element_node: (Herb::AST::HTMLElementNode) -> void
+
+      # : () -> String
+      def inspect: () -> String
+
+      private
+
+      # : () -> Herb::AST::RubyLiteralNode
+      def content_node: () -> Herb::AST::RubyLiteralNode
+
+      # : (Herb::AST::HTMLElementNode) -> bool
+      def matches?: (Herb::AST::HTMLElementNode) -> bool
+
+      # : (Hash[String, String?], String, untyped) -> bool
+      def attribute_matches?: (Hash[String, String?], String, untyped) -> bool
+
+      # : (Herb::AST::HTMLElementNode) -> Hash[String, String?]
+      def element_attributes: (Herb::AST::HTMLElementNode) -> Hash[String, String?]
+
+      # : (Herb::AST::HTMLAttributeNode) -> String?
+      def attribute_name: (Herb::AST::HTMLAttributeNode) -> String?
+
+      # : (Herb::AST::HTMLAttributeNode) -> String?
+      def attribute_value: (Herb::AST::HTMLAttributeNode) -> String?
+    end
+  end
+end

data/sig/herb/engine/{debug_visitor.rbs → visitors/debug_visitor.rbs}

@@ -1,9 +1,22 @@
-# Generated from lib/herb/engine/debug_visitor.rb with RBS::Inline
+# Generated from lib/herb/engine/visitors/debug_visitor.rb with RBS::Inline
 
 module Herb
   class Engine
     class DebugVisitor < Herb::Visitor
-      def initialize: (?file_path: untyped, ?project_path: untyped) -> untyped
+      include Herb::Visitor::ContextAware
+
+      # : () -> bool
+      def self.reads_erb_source?: () -> bool
+
+      # `node` adds the render occurrence to every marker, which needs `InstrumentationVisitor` in the
+      # same stack to have anything to report. Without it the value is empty on every tag, so it is
+      # asked for rather than assumed.
+      #
+      #     Herb::Engine.new(source, visitors: [
+      #       Herb::Engine::DebugVisitor.new(node: true),
+      #       Herb::Engine::InstrumentationVisitor.new
+      #     ])
+      def initialize: (?node: untyped) -> untyped
 
       def visit_document_node: (untyped node) -> untyped
 
@@ -21,19 +34,17 @@ module Herb
 
       def visit_erb_block_node: (untyped node) -> untyped
 
-      private
+      def visit_erb_iteration_block_node: (untyped node) -> untyped
 
-      def calculate_relative_path: () -> untyped
+      def inspect: () -> untyped
 
-      def wrap_all_erb_nodes: (untyped node) -> untyped
+      private
 
-      # Creates a dummy location for AST nodes that don't need real location info
-      # : () -> Herb::Location
-      def dummy_location: () -> Herb::Location
+      def filename: () -> untyped
 
-      # Creates a dummy range for tokens that don't need real range info
-      # : () -> Herb::Range
-      def dummy_range: () -> Herb::Range
+      def relative_file_path: () -> untyped
+
+      def wrap_all_erb_nodes: (untyped node) -> untyped
 
       def replace_erb_nodes_recursive: (untyped node) -> untyped
 
@@ -45,9 +56,11 @@ module Herb
 
       def add_debug_attributes_to_element: (untyped open_tag_node) -> untyped
 
-      def create_debug_attribute: (untyped name, untyped value) -> untyped
+      def create_debug_node_attribute: () -> untyped
 
-      def create_token: (untyped type, untyped value) -> untyped
+      def current_node_erb: () -> untyped
+
+      def create_debug_attribute: (untyped name, untyped value) -> untyped
 
       def create_debug_span_for_erb: (untyped erb_node) -> untyped
 
@@ -69,8 +82,6 @@ module Herb
 
       def in_excluded_context?: () -> untyped
 
-      def erb_output?: (untyped opening) -> untyped
-
       # TODO: Rewrite using Prism Nodes once available
       def complex_rails_helper?: (untyped code) -> untyped
 

data/sig/herb/engine/visitors/html_safe_assertions_visitor.rbs

@@ -0,0 +1,100 @@
+# Generated from lib/herb/engine/visitors/html_safe_assertions_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Wraps the receiver of every `.html_safe` call in a template with a runtime assertion, so
+    # that marking a value as HTML-safe raises when the value contains HTML that the browser
+    # executes.
+    #
+    # This visitor is not loaded by default. Require it explicitly and pass it to the engine:
+    #
+    #     require "herb/engine/visitors/html_safe_assertions_visitor"
+    #
+    #     Herb::Engine.new(source, visitors: [Herb::Engine::HTMLSafeAssertionsVisitor.new])
+    #
+    # `<%= @user.bio.html_safe %>` then compiles as if the template had been written as:
+    #
+    #     <%= ::Herb::Engine::Runtime::HTMLSafeAssertions.check(@user.bio, file: __FILE__, line: 1, column: 1, source: "<%= @user.bio.html_safe %>", mode: :raise).html_safe %>
+    #
+    # The assertion runs on every render, and the value keeps flowing through `.html_safe`
+    # unchanged. See `Herb::Engine::Runtime::HTMLSafeAssertions` for what counts as unsafe.
+    #
+    # The calls are found in the Prism program the parser attaches to the document, which the
+    # engine enables through `required_parser_option`. Parsing an AST for this visitor by hand
+    # needs the same option:
+    #
+    #     Herb.parse(source, prism_program: true)
+    class HTMLSafeAssertionsVisitor < Herb::Visitor
+      include Herb::Visitor::ContextAware
+
+      RUNTIME: ::String
+
+      MAX_SOURCE_LENGTH: ::Integer
+
+      class MissingPrismProgramError < StandardError
+      end
+
+      # : (?mode: Symbol, ?ignore: Array[Symbol], ?file_path: (String | ::Pathname)?) -> void
+      def initialize: (?mode: Symbol, ?ignore: Array[Symbol], ?file_path: (String | ::Pathname)?) -> void
+
+      # : (Herb::AST::DocumentNode) -> void
+      def visit_document_node: (Herb::AST::DocumentNode) -> void
+
+      # : (Herb::AST::Node) -> void
+      def visit_erb_node: (Herb::AST::Node) -> void
+
+      # : () -> String
+      def inspect: () -> String
+
+      private
+
+      # : (Symbol) -> Symbol
+      def validated_mode: (Symbol) -> Symbol
+
+      # : (Array[Symbol]) -> Array[Symbol]
+      def validated_ignore: (Array[Symbol]) -> Array[Symbol]
+
+      # : (Herb::AST::DocumentNode) -> void
+      def add_assertions: (Herb::AST::DocumentNode) -> void
+
+      # : (Herb::AST::DocumentNode) -> Array[[Symbol, Prism::Location]]
+      def html_safe_targets: (Herb::AST::DocumentNode) -> Array[[ Symbol, Prism::Location ]]
+
+      # : (Prism::Node) -> [Symbol, Prism::Location]?
+      def target_for: (Prism::Node) -> [ Symbol, Prism::Location ]?
+
+      # : (Prism::CallNode) -> bool
+      def html_safe_call?: (Prism::CallNode) -> bool
+
+      # : (Prism::BlockArgumentNode) -> bool
+      def html_safe_symbol?: (Prism::BlockArgumentNode) -> bool
+
+      # : (untyped, Array[[Symbol, Prism::Location]]) -> void
+      def rewrite: (untyped, Array[[ Symbol, Prism::Location ]]) -> void
+
+      # : (Symbol, Prism::Location, Herb::Range) -> [Symbol, Integer, Integer]?
+      def local_target: (Symbol, Prism::Location, Herb::Range) -> [ Symbol, Integer, Integer ]?
+
+      # : (Array[[Symbol, Integer, Integer]], String) -> Array[[Integer, Integer, String]]
+      def edits: (Array[[ Symbol, Integer, Integer ]], String) -> Array[[ Integer, Integer, String ]]
+
+      # : (String, Integer, Integer, String) -> String
+      def splice: (String, Integer, Integer, String) -> String
+
+      # : (untyped) -> Herb::Token?
+      def content_token: (untyped) -> Herb::Token?
+
+      # : (untyped, String) -> String
+      def check_arguments: (untyped, String) -> String
+
+      # : () -> String
+      def file_argument: () -> String
+
+      # : (untyped, String) -> String
+      def erb_source: (untyped, String) -> String
+
+      # : (String) -> String
+      def truncate: (String) -> String
+    end
+  end
+end

data/sig/herb/engine/visitors/instrumentation_visitor.rbs

@@ -0,0 +1,111 @@
+# Generated from lib/herb/engine/visitors/instrumentation_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Wraps every ERB tag in a call that says which tag is rendering, so that whatever happens
+    # while it renders can be attributed to it rather than to the template as a whole.
+    #
+    # This is half of a mechanism and does nothing by itself. It supplies where, and something else
+    # has to supply what. A template compiled with it and rendered with nothing watching records no
+    # entries at all, and only costs a call per tag. What makes it worth having is anything that
+    # calls `Herb::Engine::Runtime::Session.observe` while a tag is rendering:
+    #
+    #     require "herb/engine/visitors/instrumentation_visitor"
+    #
+    #     engine = Herb::Engine.new(source, visitors: [Herb::Engine::InstrumentationVisitor.new])
+    #
+    #     ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+    #       Herb::Engine::Runtime::Session.observe(:queries, payload[:sql]) unless payload[:cached]
+    #     end
+    #
+    #     session = Herb::Engine::Runtime::Session.capture { render(engine.src) }
+    #
+    #     session.measure(:queries, origin: "Herb Engine", code: "sql-queries") do |queries|
+    #       "#{queries.size} SQL queries"
+    #     end
+    #     #=> app/views/posts/_card.html.erb:7:8: [sql-queries] 3 SQL queries
+    #
+    # Nothing about that subscription is Herb's, which is the point. Because what gets watched is
+    # decided at render time rather than compiled in, adding a producer never means recompiling a
+    # template, and Herb never has to ship a class per thing worth watching.
+    #
+    # A tag that opens a block, or that assigns to a local, is framed from the outside rather than
+    # wrapped, because wrapping either one would change what the template means: a block would lose
+    # its body, and an assignment would bind inside the wrapper instead of the template.
+    class InstrumentationVisitor < Herb::Visitor
+      extend Herb::Visitor::Experimental
+
+      include Herb::Visitor::ContextAware
+
+      SESSION: ::String
+
+      ARRAY_PROPERTIES: untyped
+
+      NODE_PROPERTIES: untyped
+
+      ASSIGNMENT_NODES: untyped
+
+      # : () -> bool
+      def self.rewrites_erb_source?: () -> bool
+
+      # : (?capture_output: (bool | ^(String) -> boolish | Regexp | Array[untyped])?) -> void
+      def initialize: (?capture_output: (bool | ^(String) -> boolish | Regexp | Array[untyped])?) -> void
+
+      def visit_document_node: (untyped node) -> untyped
+
+      def inspect: () -> untyped
+
+      private
+
+      def frame_render: (untyped node) -> untyped
+
+      def instrument: (untyped node) -> untyped
+
+      def rewrite: (untyped nodes) -> untyped
+
+      # : (Herb::AST::Node, Herb::Visitor::Context::Origin::Entry) -> Array[Herb::AST::Node]
+      def rewrite_import: (Herb::AST::Node, Herb::Visitor::Context::Origin::Entry) -> Array[Herb::AST::Node]
+
+      # : (Herb::AST::Node) -> Array[Herb::AST::Node]
+      def rewrite_node: (Herb::AST::Node) -> Array[Herb::AST::Node]
+
+      # : (Herb::AST::Node, Herb::AST::Node) -> Herb::AST::Node
+      def replacing: (Herb::AST::Node, Herb::AST::Node) -> Herb::AST::Node
+
+      def framed?: (untyped node) -> untyped
+
+      def assignment?: (untyped node) -> untyped
+
+      def block?: (untyped node) -> untyped
+
+      def via: (untyped node) -> untyped
+
+      def wrapped_output: (untyped node) -> untyped
+
+      def captured?: (untyped node) -> untyped
+
+      def wrapped_statement: (untyped node) -> untyped
+
+      # : (String) -> bool
+      def spans_lines?: (String) -> bool
+
+      def enter_node: (untyped node) -> untyped
+
+      def leave_node: (untyped node) -> untyped
+
+      def enter_render_node: (untyped node, untyped file) -> untyped
+
+      def render_arguments: (untyped file) -> untyped
+
+      def digest_for: (untyped file) -> untyped
+
+      def leave_render_node: (untyped node) -> untyped
+
+      def position: (untyped node) -> untyped
+
+      def code: (untyped node) -> untyped
+
+      def erb_node: (untyped node, untyped opening, untyped code) -> untyped
+    end
+  end
+end

data/sig/herb/engine/visitors/optimize_visitor.rbs

@@ -0,0 +1,246 @@
+# Generated from lib/herb/engine/visitors/optimize_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Asks the parser to resolve Action View helpers into the markup they produce, so the compiler
+    # emits that markup directly instead of a call the renderer has to make. Passing it is the
+    # whole opt-in:
+    #
+    #     Herb::Engine.new(source, visitors: [Herb::Engine::OptimizeVisitor.new])
+    #
+    # There is no check first for whether a template looks like it contains helpers, because a
+    # caller that added this has already answered that question.
+    #
+    # An output tag whose Ruby is a single string, integer, or float literal renders the same text
+    # every time, so the visitor folds it into the template text around it. `<%= "hello" %>`
+    # compiles to the text `hello`, with nothing left to evaluate when the template renders. The
+    # escaping the compiler would have arranged at render time is applied once here instead, by the
+    # same functions it would have called, so the fold produces byte for byte what the expression
+    # would have, in an attribute value and inside `<script>` or `<style>` just as in plain
+    # content. A caller that swapped one of those functions out through `escapefunc`, `attrfunc`,
+    # `jsfunc`, or `cssfunc` gets the fold only when the stock function leaves the value untouched,
+    # on the grounds that an escape function has nothing to do there either.
+    #
+    # A literal that spans lines, sits in a trimming tag, or renders nothing at all stays dynamic,
+    # so folding never moves another tag off the line it was written on and never changes how the
+    # whitespace around the tag is handled. Folding rewrites the ERB a template was written with,
+    # so a visitor that reads it, like `Slots::Visitor`, has to run earlier in the stack, and the
+    # stack raises when it does not.
+    #
+    # Its presence also lets the engine collapse a template that carries no Ruby into the single
+    # string literal it renders, skipping the buffer the compiler would otherwise build up. A
+    # template that was HTML to begin with qualifies, and so does one left fully static once the
+    # helpers above resolved to markup and the literal outputs folded into text. The collapse is
+    # held back when the caller drives the buffer itself through `preamble`, `postamble`, `bufval`,
+    # or `ensure`, and when a visitor recorded a diagnostic that the compiled template still needs
+    # to report.
+    #
+    # A template whose only Ruby is conditional chains over otherwise static markup collapses the
+    # same way, nesting included. `if`, `unless`, and `elsif` qualify, and so do `case` with its
+    # `when` branches and `case` matching with `in` patterns. Each render path becomes one frozen
+    # string literal holding everything that path renders, the markup around and between the
+    # conditionals included, and the compiled template is the chains themselves picking between
+    # them. The conditions compile onto the lines they were written on, so backtraces stay right.
+    # A chain without an `else` gets one that returns what the template renders without it, except
+    # a pattern matching chain, which keeps raising `NoMatchingPatternError` for a value no
+    # pattern accepts, the way it rendered before the collapse.
+    #
+    # The path literals repeat the markup the paths share, so the collapse steps back when they
+    # would hold more than `DUPLICATION_LIMIT` times the template's static bytes, and the buffer
+    # stays. A chain that sits beside another in the same scope keeps the buffer too.
+    #
+    # A template the collapse walks away from can still get its static subtrees. With
+    # `subtrees: true`, when the buffer stays, a chain whose branches are static collapses into a
+    # single append of the chain picking between path literals, the static text around it merged
+    # in, so a conditional attribute next to a dynamic one costs one append where it cost three.
+    # A chain the buffer already renders in one append is left as it was, and the duplication
+    # limit governs each subtree the way it governs the template. The pass trades compiled
+    # template bytes for fewer appends at render time, which is why it is the one pass that is
+    # off by default.
+    #
+    # Every other pass is on by default, and each can be left off on its own. `helpers: false` stops
+    # asking the parser to resolve helpers, `conditionals: false` stops asking it to unroll the
+    # postfix conditionals and ternaries it would have, `literals: false` keeps literal outputs
+    # dynamic, and `collapse: false` keeps the buffer for a template either collapse above would
+    # have compiled without one:
+    #
+    #     Herb::Engine::OptimizeVisitor.new(literals: false, collapse: false)
+    #
+    # Turning a parser-side pass off only withdraws this visitor's request for the parser option
+    # behind it. A caller that asks for `action_view_helpers: true` through `parser_options` still
+    # gets the resolution the parser was asked for directly, and `verify` below still covers what
+    # it resolved. Unrolling is also part of how the parser resolves helpers, since a helper
+    # behind a modifier has to come out of it first, so a modifier keeps its written shape only
+    # once `helpers` is off too.
+    #
+    # Replacing a helper call with its markup is only the same thing as calling it while the helper
+    # is the one it was resolved against. An application that defines its own `content_tag` gets the
+    # stock markup instead, everywhere, with nothing at the call site to say so. `verify` compiles a
+    # check into the template that runs when it renders and reports a helper that has since been
+    # overwritten:
+    #
+    #     Herb::Engine::OptimizeVisitor.new(verify: true)
+    #
+    # It costs a call per render and reports rather than corrects, so it earns its place in
+    # development and not in production. Compiling it in is the caller's decision for the same reason
+    # the optimization itself is.
+    class OptimizeVisitor < Herb::Visitor
+      extend Herb::Visitor::Experimental
+
+      include Herb::Visitor::ContextAware
+
+      SESSION: String
+
+      CODE: String
+
+      ORIGIN: String
+
+      OUTPUT_OPENINGS: Array[String]
+
+      CHILD_LISTS: Array[Symbol]
+
+      BRANCHLESS_KEYWORDS: Array[Symbol]
+
+      CHAIN_OPENINGS: Array[Symbol]
+
+      DUPLICATION_LIMIT: Integer
+
+      # : () -> Array[String]
+      def self.helper_sources: () -> Array[String]
+
+      # : () -> bool
+      def self.rewrites_erb_source?: () -> bool
+
+      # : (?helpers: bool, ?conditionals: bool, ?literals: bool, ?collapse: bool, ?subtrees: bool, ?verify: bool) -> void
+      def initialize: (?helpers: bool, ?conditionals: bool, ?literals: bool, ?collapse: bool, ?subtrees: bool, ?verify: bool) -> void
+
+      # : () -> Hash[Symbol, untyped]
+      def required_parser_options: () -> Hash[Symbol, untyped]
+
+      # : (Herb::AST::DocumentNode) -> void
+      def visit_document_node: (Herb::AST::DocumentNode) -> void
+
+      # : (Herb::AST::Node) -> void
+      def visit_node: (Herb::AST::Node) -> void
+
+      # : (Herb::AST::HTMLElementNode) -> void
+      def visit_html_element_node: (Herb::AST::HTMLElementNode) -> void
+
+      # : (Herb::AST::HTMLConditionalElementNode) -> void
+      def visit_html_conditional_element_node: (Herb::AST::HTMLConditionalElementNode) -> void
+
+      # : (Herb::AST::HTMLAttributeValueNode) -> void
+      def visit_html_attribute_value_node: (Herb::AST::HTMLAttributeValueNode) -> void
+
+      # : (Herb::Engine, untyped) -> String?
+      def compile_static_body: (Herb::Engine, untyped) -> String?
+
+      # : () -> String
+      def inspect: () -> String
+
+      private
+
+      # : () -> Array[String]
+      def non_default_toggles: () -> Array[String]
+
+      # : (Herb::Engine, untyped) -> String?
+      def static_body: (Herb::Engine, untyped) -> String?
+
+      # : (Herb::Engine, Array[untyped]) -> void
+      def collapse_subtrees: (Herb::Engine, Array[untyped]) -> void
+
+      # : ((Herb::AST::HTMLElementNode | Herb::AST::HTMLConditionalElementNode)) -> Symbol?
+      def element_output_context: (Herb::AST::HTMLElementNode | Herb::AST::HTMLConditionalElementNode) -> Symbol?
+
+      # : (Symbol?) { () -> void } -> void
+      def with_output_context: (Symbol?) { () -> void } -> void
+
+      # : () -> Symbol
+      def current_output_context: () -> Symbol
+
+      # : (Herb::AST::Node?) -> Herb::AST::LiteralNode?
+      def folded_literal: (Herb::AST::Node?) -> Herb::AST::LiteralNode?
+
+      # : (String) -> String?
+      def literal_value: (String) -> String?
+
+      # : (String, String) -> String?
+      def output_text: (String, String) -> String?
+
+      # : (String, Symbol) { () -> String } -> String?
+      def escaped_output: (String, Symbol) { () -> String } -> String?
+
+      # : (String) -> bool
+      def escape_output?: (String) -> bool
+
+      # : (Herb::Engine, Array[untyped]) -> String?
+      def compile_static_branches: (Herb::Engine, Array[untyped]) -> String?
+
+      # : (Array[untyped]) -> Hash[Symbol, untyped]?
+      def branch_tree: (Array[untyped]) -> Hash[Symbol, untyped]?
+
+      # : (Array[untyped], Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def tree_step: (Array[untyped], Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (Symbol, String, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def tree_transition: (Symbol, String, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def open_chain: (Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (String, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def open_case_chain: (String, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (Symbol, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def open_case_branch: (Symbol, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (Symbol, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def open_branch: (Symbol, Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+      def close_chain: (Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]) -> untyped
+
+      # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]?
+      def container_chain: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]?
+
+      # : (Hash[Symbol, untyped]) -> [String, String]
+      def chain_surroundings: (Hash[Symbol, untyped]) -> [ String, String ]
+
+      # : (Hash[Symbol, untyped]) -> Array[String]
+      def container_paths: (Hash[Symbol, untyped]) -> Array[String]
+
+      # : (Array[String], Array[untyped]) -> bool
+      def within_duplication_limit?: (Array[String], Array[untyped]) -> bool
+
+      # : (Herb::Engine, Hash[Symbol, untyped], String, String, Hash[Symbol, Array[String?]]) -> void
+      def collect_leaf_literals: (Herb::Engine, Hash[Symbol, untyped], String, String, Hash[Symbol, Array[String?]]) -> void
+
+      # : (Herb::Engine, Array[untyped], Integer) -> [::Range[Integer], Array[untyped]]?
+      def chain_run_replacement: (Herb::Engine, Array[untyped], Integer) -> [ ::Range[Integer], Array[untyped] ]?
+
+      # : (Array[untyped], Integer) -> Integer?
+      def chain_end_index: (Array[untyped], Integer) -> Integer?
+
+      # : (Hash[Symbol, untyped]) -> bool
+      def nested_chain?: (Hash[Symbol, untyped]) -> bool
+
+      # : (String) -> Symbol?
+      def chain_keyword: (String) -> Symbol?
+
+      # : (Herb::Engine, Array[untyped], Hash[Symbol, untyped]) -> String
+      def render_static_branches: (Herb::Engine, Array[untyped], Hash[Symbol, untyped]) -> String
+
+      # : (String?, Herb::Location?) -> void
+      def collect: (String?, Herb::Location?) -> void
+
+      # : (Herb::AST::DocumentNode) -> Herb::AST::ERBContentNode
+      def check_node: (Herb::AST::DocumentNode) -> Herb::AST::ERBContentNode
+
+      # : (String, Herb::Location?) -> String
+      def check_for: (String, Herb::Location?) -> String
+
+      # : (String, String, Herb::Location?) -> String
+      def entry_for: (String, String, Herb::Location?) -> String
+    end
+  end
+end