herb 0.10.1 → 0.11.1

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

@@ -0,0 +1,66 @@
+# Generated from lib/herb/engine/visitors/remove_comments_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Removes comments from the template, so that the compiled output never contains one.
+    #
+    # An HTML comment is served to the browser and is readable by anyone who looks at the page
+    # source, so a note the template author wrote for other developers ends up in production.
+    # This drops every `<!-- -->` comment, along with everything nested inside it, before the
+    # compiler sees the template. ERB inside a removed comment is dropped with it and never runs.
+    #
+    # ERB comments go too. The compiler already leaves `<%# comment %>` and `<% # comment %>` out
+    # of the output on its own, so removing them makes it something the template is guaranteed
+    # instead of something the compiler happens to do.
+    #
+    # What Herb writes to itself is not a comment. A directive, which is an ERB comment whose
+    # content starts with `herb:` or `locals:`, is an instruction to Herb or to Action View
+    # instead of a note for people, so `<%# herb:state %>`, `<%# herb:key %>`,
+    # `<%# herb:disable %>` and `<%# locals: (title:) %>` all stay where they are. The compiler
+    # leaves them out of the output the same way it leaves any ERB comment out.
+    #
+    # A marker, which `Slots::Markers` recognizes, is how a pass hands something to the browser,
+    # the way `Slots::Visitor` writes `<!--herb-slot:0-->` around a slot. Those stay too, in the
+    # output as well, so this visitor can run before or after the pass that writes them.
+    #
+    # Whitespace around a comment is left alone, so removing one never changes how the elements
+    # next to it are laid out. A comment on a line of its own leaves that line's whitespace
+    # behind, an ERB comment included, which the compiler on its own would have trimmed away with
+    # the line.
+    #
+    # Comment syntax inside a `<script>` or `<style>` element is part of that element's text
+    # instead of an HTML comment, so it stays. A conditional comment is an HTML comment, so it
+    # goes, and the markup it guards goes with it.
+    #
+    # This visitor is not loaded by default. Require it explicitly and pass it to the engine:
+    #
+    #     require "herb/engine/visitors/remove_comments_visitor"
+    #
+    #     Herb::Engine.new(source, visitors: [Herb::Engine::RemoveCommentsVisitor.new])
+    class RemoveCommentsVisitor < Herb::Visitor
+      CHILD_LISTS: Array[Symbol]
+
+      DIRECTIVE: Regexp
+
+      # : (Herb::AST::Node) -> void
+      def visit_node: (Herb::AST::Node) -> void
+
+      # : () -> String
+      def inspect: () -> String
+
+      private
+
+      # : (Herb::AST::Node?) -> bool
+      def comment?: (Herb::AST::Node?) -> bool
+
+      # : (Herb::AST::HTMLCommentNode) -> bool
+      def marker?: (Herb::AST::HTMLCommentNode) -> bool
+
+      # : (Herb::AST::HTMLCommentNode) -> String
+      def comment_text: (Herb::AST::HTMLCommentNode) -> String
+
+      # : (Herb::AST::ERBCommentNode | Herb::AST::ERBContentNode) -> bool
+      def directive?: (Herb::AST::ERBCommentNode | Herb::AST::ERBContentNode) -> bool
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# Generated from lib/herb/engine/visitors/source_attribution_visitor.rb with RBS::Inline
+
+module Herb
+  class Engine
+    # Stamps every element with the template and the position it was written at, so that something
+    # found on the rendered page can be pointed back at the line that produced it.
+    #
+    # Some things are only visible once a page is rendered. Two partials can each be valid on their
+    # own and still collide on an `id`, a heading order only exists once a layout and everything it
+    # renders are composed, and a `<form>` inside another `<form>` is usually two templates that
+    # never see each other. Linting the response is what answers those, and the positions it reports
+    # are offsets into the response, which is not a place anyone can go and fix anything. This is
+    # what turns them back into a file and a line.
+    #
+    #     require "herb/engine/visitors/source_attribution_visitor"
+    #
+    #     Herb::Engine.new(source, filename: path, visitors: [
+    #       Herb::Engine::SourceAttributionVisitor.new
+    #     ])
+    #
+    #     #=> <div data-herb-source="app/views/posts/_card.html.erb:8:3">
+    #
+    # A tag helper is stamped too. The `action_view_helpers` parser option turns
+    # `<%= link_to "Home", "/" %>` into an `<a>` that the compiler writes out as markup, and that
+    # `<a>` is stamped at the position of the `<%=` that asked for it.
+    #
+    #     #=> <a href="/" data-herb-source="app/views/posts/_card.html.erb:4:5">Home</a>
+    #
+    # That option is recommended here, so a stack that says nothing about it gets it. It is worth
+    # knowing that it decides more than attribution does. It is also what makes the compiler write
+    # a helper out as markup instead of calling it while the page renders, which is the same thing
+    # `OptimizeVisitor` and `Slots::Visitor` require it for. A host that wants its helpers called at
+    # render time sets `action_view_helpers: false` and takes the warning that comes with it, and
+    # everything written as literal markup is stamped either way.
+    #
+    # A helper the parser cannot resolve to a tag stays an ERB node with no element around it, so
+    # `form_with` and anything the host defined itself reach the response carrying nothing, and the
+    # nearest stamped ancestor is what places them.
+    #
+    # Nothing is wrapped to close that gap. A wrapper element inside `<ul>`, `<table>` or `<select>`
+    # is invalid markup, and it would be Herb's own markup tripping the structural rules this exists
+    # to run. An unstamped element is a worse answer that stays true. A wrong one would not.
+    #
+    # A partial that `InlineRender::Visitor` brought into this template is stamped with the file it
+    # was written in, not the file it was inlined into.
+    #
+    # The stamp is markup Herb added, so a consumer is expected to strip it before reporting
+    # positions back, and to leave the visitor out of anything but a development build.
+    class SourceAttributionVisitor < Herb::Visitor
+      include Herb::Visitor::ContextAware
+
+      ATTRIBUTE: String
+
+      # : (?attribute: String) -> void
+      def initialize: (?attribute: String) -> void
+
+      # : (Herb::AST::HTMLElementNode) -> void
+      def visit_html_element_node: (Herb::AST::HTMLElementNode) -> void
+
+      # : (Herb::AST::Node) -> void
+      def visit_child_nodes: (Herb::AST::Node) -> void
+
+      # : () -> String
+      def inspect: () -> String
+
+      private
+
+      # : () -> String
+      def current_file: () -> String
+
+      # : (Herb::AST::Node?) -> void
+      def stamp_open_tag: (Herb::AST::Node?) -> void
+
+      # : (Herb::AST::Node?) -> void
+      def stamp: (Herb::AST::Node?) -> void
+
+      # : ((Herb::AST::HTMLOpenTagNode | Herb::AST::ERBOpenTagNode)) -> Herb::serialized_position?
+      def position_of: (Herb::AST::HTMLOpenTagNode | Herb::AST::ERBOpenTagNode) -> Herb::serialized_position?
+
+      # : ((Herb::AST::HTMLOpenTagNode | Herb::AST::ERBOpenTagNode)) -> bool
+      def stamped?: (Herb::AST::HTMLOpenTagNode | Herb::AST::ERBOpenTagNode) -> bool
+
+      # : (Herb::AST::HTMLAttributeNode) -> String?
+      def attribute_name: (Herb::AST::HTMLAttributeNode) -> String?
+
+      # : (String, String) -> Herb::AST::HTMLAttributeNode
+      def attribute_node: (String, String) -> Herb::AST::HTMLAttributeNode
+    end
+  end
+end

data/sig/herb/engine.rbs

@@ -2,50 +2,42 @@
 
 module Herb
   class Engine
-    attr_reader src: untyped
+    attr_reader src: String
 
-    attr_reader filename: untyped
+    attr_reader context: Visitor::Context
 
-    attr_reader project_path: untyped
+    attr_reader bufvar: String
 
-    attr_reader relative_file_path: untyped
+    attr_reader visitors: Visitor::Stack
 
-    attr_reader bufvar: untyped
+    # : () -> Pathname?
+    def filename: () -> Pathname?
 
-    attr_reader debug: untyped
+    # : () -> Pathname
+    def project_path: () -> Pathname
 
-    attr_reader content_for_head: untyped
+    # : () -> String
+    def relative_file_path: () -> String
 
-    attr_reader validation_error_template: untyped
+    # : (String) -> String
+    def string_literal: (String) -> String
 
-    attr_reader visitors: untyped
+    STRING_LITERAL_ESCAPES: Hash[String, String]
 
-    attr_reader enabled_validators: untyped
-
-    def self.optimize_warning_issued: () -> bool
-
-    def self.optimize_warning_issued=: (bool) -> bool
-
-    attr_accessor optimize_warning_issued: bool
+    # : (String) -> String
+    def escaped_string_literal: (String) -> String
 
     ESCAPE_TABLE: untyped
 
-    class CompilationError < StandardError
-    end
-
-    class GeneratorTemplateError < CompilationError
-    end
-
-    class InvalidRubyError < CompilationError
-      attr_reader compiled_source: untyped
-
-      def initialize: (untyped message, ?compiled_source: untyped) -> untyped
-    end
+    ATTRIBUTE_ESCAPE_TABLE: untyped
 
     def initialize: (untyped input, ?untyped properties) -> untyped
 
     def self.h: (untyped value) -> untyped
 
+    # : (untyped) -> String
+    def self.raw: (untyped) -> String
+
     def self.attr: (untyped value) -> untyped
 
     def self.js: (untyped value) -> untyped
@@ -54,13 +46,8 @@ module Herb
 
     def self.nested_attribute_value: (untyped value) -> untyped
 
-    def self.comment?: (untyped code) -> untyped
-
-    def self.heredoc?: (untyped code) -> untyped
-
-    def source_may_contain_action_view_helpers?: (untyped source) -> untyped
-
-    def self.action_view_helper_pattern: () -> untyped
+    # : () -> untyped
+    def compiler_class: () -> untyped
 
     def add_text: (untyped text) -> untyped
 
@@ -96,20 +83,39 @@ module Herb
 
     private
 
-    def run_validation: (untyped ast) -> untyped
+    # : (Hash[Symbol, untyped]) -> bool
+    def buffer_required?: (Hash[Symbol, untyped]) -> bool
+
+    # : (String) -> String
+    def wrap_postamble: (String) -> String
+
+    # : (untyped) -> String?
+    def compile_static_body: (untyped) -> String?
+
+    # : () -> Array[Herb::Diagnostic]
+    def collected_diagnostics: () -> Array[Herb::Diagnostic]
+
+    # : (Hash[Symbol, untyped], String) -> void
+    def write_buffer_prelude: (Hash[Symbol, untyped], String) -> void
+
+    # : () -> void
+    def insert_herb_alias!: () -> void
 
     def handle_parser_errors: (untyped parser_errors, untyped input, untyped _ast) -> untyped
 
-    def handle_validation_errors: (untyped validators, untyped input) -> untyped
+    # : (String) -> void
+    def report: (String) -> void
 
-    def add_validation_overlay: (untyped validators, ?untyped input) -> untyped
+    # : (Array[Herb::Diagnostic]) -> void
+    def emit_compile_diagnostics: (Array[Herb::Diagnostic]) -> void
 
-    def escape_attr: (untyped text) -> untyped
+    # : (Array[Herb::Diagnostic], String) -> void
+    def raise_for: (Array[Herb::Diagnostic], String) -> void
 
-    def add_parser_error_overlay: (untyped parser_errors, untyped input) -> untyped
+    def context_options: (untyped properties) -> untyped
 
-    # : () -> Array[Herb::Visitor]
-    def default_visitors: () -> Array[Herb::Visitor]
+    # : () -> Hash[Symbol, untyped]
+    def parse_options: () -> Hash[Symbol, untyped]
 
     # : () -> Hash[Symbol, untyped]
     def default_parser_options: () -> Hash[Symbol, untyped]

data/sig/herb/ensure_installed.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/herb/ensure_installed.rb with RBS::Inline
+
+module Herb
+  # : (*String gems) -> void
+  def self.ensure_installed: (*String gems) -> void
+
+  # : (Array[String]) -> void
+  def self.refuse_bundle_replacement: (Array[String]) -> void
+end