herb 0.10.4 → 0.11.0

data/lib/herb/visitor/context.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+# typed: false
+
+require "pathname"
+
+require_relative "../analysis/partial_resolver"
+require_relative "context/origin"
+require_relative "context/replacements"
+
+module Herb
+  class Visitor
+    # Per-template information the engine hands to the visitors it runs before compilation.
+    #
+    # Alongside the template path, it carries the options the engine was built with, and any
+    # additional keys the caller wants to pass through to its own visitors:
+    #
+    #     Herb::Engine.new(source, filename: path, context: { theme: "dark" }, visitors: [MyVisitor.new])
+    #
+    #     class MyVisitor < Herb::Visitor
+    #       include Herb::Visitor::ContextAware
+    #
+    #       def visit_html_element_node(node)
+    #         context.relative_file_path #=> "app/views/users/show.html.erb"
+    #         context.options[:escape]   #=> true
+    #         context[:theme]            #=> "dark"
+    #
+    #         super
+    #       end
+    #     end
+    #
+    class Context
+      UNKNOWN_FILE_PATH = "unknown" #: String
+
+      attr_reader :file_path #: Pathname?
+      attr_reader :options #: Hash[Symbol, untyped]
+      attr_reader :data #: Hash[Symbol, untyped]
+
+      #: (?file_path: (String | Pathname)?, ?project_path: (String | Pathname)?, ?options: Hash[Symbol, untyped], ?resolver: untyped, **untyped) -> void
+      def initialize(file_path: nil, project_path: nil, options: {}, resolver: nil, **data)
+        @file_path = self.class.coerce_file_path(file_path)
+        @project_path_cache = [] #: Array[Pathname]
+        @project_path_cache << self.class.coerce_project_path(project_path) if project_path
+        @relative_file_path_cache = [] #: Array[String]
+        @resolver_cache = [] #: Array[untyped]
+        @resolver_cache << resolver if resolver
+        @options = options.dup.freeze
+        @data = self.class.with_records(data).freeze
+
+        freeze
+      end
+
+      #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def self.with_records(data)
+        data[:origin] ||= Origin.new
+        data[:replacements] ||= Replacements.new
+
+        data
+      end
+
+      #: () -> Pathname
+      def project_path
+        @project_path_cache[0] ||= self.class.coerce_project_path(nil)
+      end
+
+      #: () -> String
+      def relative_file_path
+        @relative_file_path_cache[0] ||= self.class.derive_relative_file_path(file_path, project_path)
+      end
+
+      #: () -> untyped
+      def resolver
+        @resolver_cache[0] ||= Analysis::PartialResolver.new(project_path)
+      end
+
+      #: () -> Herb::Visitor::Context::Origin
+      def origin
+        data[:origin]
+      end
+
+      #: () -> Herb::Visitor::Context::Replacements
+      def replacements
+        data[:replacements]
+      end
+
+      #: (Symbol) -> untyped
+      def [](key)
+        case key
+        when :file_path then file_path
+        when :project_path then project_path
+        when :relative_file_path then relative_file_path
+        when :options then options
+        when :resolver then resolver
+        else data[key]
+        end
+      end
+
+      #: (Symbol) -> bool
+      def key?(key)
+        [:file_path, :project_path, :relative_file_path, :options, :resolver].include?(key) || data.key?(key)
+      end
+
+      #: (Symbol, ?untyped) -> untyped
+      def fetch(key, *default)
+        return self[key] if key?(key)
+        return default.first unless default.empty?
+
+        raise KeyError, "key not found: #{key.inspect}"
+      end
+
+      #: (**untyped) -> Herb::Visitor::Context
+      def merge(**extra)
+        self.class.new(
+          file_path: extra.fetch(:file_path, file_path),
+          project_path: extra.fetch(:project_path, project_path),
+          options: extra.fetch(:options, options),
+          resolver: extra.fetch(:resolver, @resolver_cache[0]),
+          **data.merge(extra.except(:file_path, :project_path, :options, :resolver))
+        )
+      end
+
+      #: () -> Hash[Symbol, untyped]
+      def to_hash
+        {
+          file_path: file_path,
+          project_path: project_path,
+          relative_file_path: relative_file_path,
+          options: options,
+          resolver: resolver,
+          data: data,
+        }
+      end
+
+      alias to_h to_hash
+
+      #: () -> String
+      def inspect
+        "#<#{self.class.name} file_path=#{file_path.to_s.inspect} relative_file_path=#{relative_file_path.inspect}>"
+      end
+
+      #: ((String | Pathname)?) -> Pathname?
+      def self.coerce_file_path(file_path)
+        case file_path
+        when ::Pathname then file_path
+        when String then file_path.empty? ? nil : ::Pathname.new(file_path)
+        end
+      end
+
+      #: ((String | Pathname)?) -> Pathname
+      def self.coerce_project_path(project_path)
+        case project_path
+        when ::Pathname then project_path
+        when String then ::Pathname.new(project_path)
+        else ::Pathname.new(Dir.pwd)
+        end
+      end
+
+      #: (Pathname?, Pathname) -> String
+      def self.derive_relative_file_path(file_path, project_path)
+        return UNKNOWN_FILE_PATH unless file_path
+
+        absolute = file_path.absolute? ? file_path : project_path + file_path
+
+        absolute.relative_path_from(project_path).to_s
+      rescue ArgumentError
+        file_path.to_s
+      end
+    end
+  end
+end

data/lib/herb/visitor/context_aware.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# typed: false
+
+require_relative "context"
+
+module Herb
+  class Visitor
+    # Opt-in for visitors that want the template information the engine was built with.
+    #
+    # `Herb::Visitor` is generated and holds no state, so a visitor asks for a context by
+    # including this module. The engine then hands it one before it walks the AST:
+    #
+    #     class MyVisitor < Herb::Visitor
+    #       include Herb::Visitor::ContextAware
+    #     end
+    #
+    #     Herb::Engine.new(source, filename: path, visitors: [MyVisitor.new])
+    #
+    # A context passed by the caller always wins over the one the engine supplies, so a
+    # visitor can also be used on its own, without an engine.
+    #
+    module ContextAware
+      #: () -> Herb::Visitor::Context
+      def context
+        @context ||= Context.new
+      end
+
+      #: (Herb::Visitor::Context) -> void
+      def context=(context)
+        @context = context
+        @context_explicit = true
+      end
+
+      #: (Herb::Visitor::Context) -> void
+      def inherit_context(context)
+        @context = context unless @context_explicit
+      end
+
+      #: () -> Herb::Visitor::Context::Origin
+      def origin
+        context.origin
+      end
+    end
+  end
+end

data/lib/herb/visitor/diagnostics.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative "../diagnostic"
+
+module Herb
+  class Visitor
+    # Opt-in for visitors that find something worth telling the developer about.
+    #
+    # A visitor records what it finds and keeps walking. The engine collects from every visitor
+    # afterwards and decides what to do with the result. That split is what lets a visitor that
+    # rewrites the tree also report, which a base class reserved for read-only validators could
+    # never do:
+    #
+    #     class MyVisitor < Herb::Visitor
+    #       include Herb::Visitor::ContextAware
+    #       include Herb::Visitor::Diagnostics
+    #
+    #       def visit_html_element_node(node)
+    #         warning("This element is suspicious.", node.location, code: "SuspiciousElement")
+    #
+    #         super
+    #       end
+    #     end
+    #
+    module Diagnostics
+      include Kernel
+
+      #: (?fatal: bool, **untyped) -> void
+      def initialize(fatal: false, **)
+        @fatal = fatal
+
+        super(**)
+      end
+
+      #: () -> bool
+      def fatal?
+        @fatal
+      end
+
+      #: (untyped) -> void
+      def self.included(base)
+        super
+
+        base.required_parser_option(track_locations: true) if base.respond_to?(:required_parser_option)
+      end
+
+      #: () -> Array[Herb::Diagnostic]
+      def diagnostics
+        @diagnostics ||= [] #: Array[Herb::Diagnostic]
+      end
+
+      #: (String, Herb::Location?, ?code: String?, ?suggestion: String?, ?docs_url: String?, ?template: String?, ?error_class: Class?) -> Herb::Diagnostic
+      def error(message, location, code: nil, suggestion: nil, docs_url: nil, template: nil, error_class: nil)
+        add_diagnostic(message, location, :error, code: code, suggestion: suggestion, docs_url: docs_url, template: template, error_class: error_class)
+      end
+
+      #: (String, Herb::Location?, ?code: String?, ?suggestion: String?, ?docs_url: String?, ?template: String?) -> Herb::Diagnostic
+      def warning(message, location, code: nil, suggestion: nil, docs_url: nil, template: nil)
+        add_diagnostic(message, location, :warning, code: code, suggestion: suggestion, docs_url: docs_url, template: template)
+      end
+
+      #: (String, Herb::Location?, ?code: String?, ?suggestion: String?, ?docs_url: String?, ?template: String?) -> Herb::Diagnostic
+      def info(message, location, code: nil, suggestion: nil, docs_url: nil, template: nil)
+        add_diagnostic(message, location, :info, code: code, suggestion: suggestion, docs_url: docs_url, template: template)
+      end
+
+      #: (String, Herb::Location?, ?code: String?, ?suggestion: String?, ?docs_url: String?, ?template: String?) -> Herb::Diagnostic
+      def hint(message, location, code: nil, suggestion: nil, docs_url: nil, template: nil)
+        add_diagnostic(message, location, :hint, code: code, suggestion: suggestion, docs_url: docs_url, template: template)
+      end
+
+      #: () -> Array[Herb::Diagnostic]
+      def errors
+        diagnostics.select(&:error?)
+      end
+
+      #: () -> Array[Herb::Diagnostic]
+      def warnings
+        diagnostics.select(&:warning?)
+      end
+
+      #: () -> bool
+      def errors?
+        diagnostics.any?(&:error?)
+      end
+
+      #: () -> bool
+      def warnings?
+        diagnostics.any?(&:warning?)
+      end
+
+      #: () -> void
+      def clear_diagnostics
+        diagnostics.clear
+      end
+
+      #: (?Symbol?) -> Integer
+      def diagnostic_count(severity = nil)
+        return diagnostics.length unless severity
+
+        diagnostics.count { |diagnostic| diagnostic.severity == severity }
+      end
+
+      private
+
+      #: (String, Herb::Location?, Symbol, ?code: String?, ?suggestion: String?, ?docs_url: String?, ?template: String?, ?error_class: Class?) -> Herb::Diagnostic
+      def add_diagnostic(message, location, severity, code: nil, suggestion: nil, docs_url: nil, template: nil, error_class: nil)
+        diagnostic = Herb::Diagnostic.new(
+          template: template || diagnostic_template,
+          message: message,
+          severity: severity,
+          origin: diagnostic_origin,
+          code: code,
+          location: location,
+          suggestion: suggestion,
+          docs_url: docs_url,
+          phase: :compile,
+          data: diagnostic_data,
+          error_class: error_class
+        )
+
+        diagnostics << diagnostic
+
+        diagnostic
+      end
+
+      #: () -> String
+      def diagnostic_origin
+        "Herb Compiler"
+      end
+
+      #: () -> Hash[Symbol, untyped]
+      def diagnostic_data
+        { validator: self.class.name&.split("::")&.last }
+      end
+
+      #: () -> String
+      def diagnostic_template
+        visitor_context = respond_to?(:context) ? send(:context) : nil
+
+        return visitor_context.relative_file_path if visitor_context.is_a?(Context)
+
+        Context::UNKNOWN_FILE_PATH
+      end
+    end
+  end
+end

data/lib/herb/visitor/experimental.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Herb
+  class Visitor
+    # Says once, for the life of a process, that a visitor is not settled yet.
+    #
+    #     class ComponentVisitor < Visitor
+    #       extend Experimental
+    #
+    #       experimental "The Component-Transform Visitor is experimental. Its output and API may change."
+    #     end
+    #
+    # The notice goes out when the first one is built, so a host that never reaches for the visitor
+    # never hears about it.
+    #
+    module Experimental
+      #: (String) -> void
+      def experimental(notice)
+        @notice = notice
+      end
+
+      #: (*untyped, **untyped) ?{ (?) -> untyped } -> untyped
+      def new(*, **, &)
+        notice = @notice
+        @notice = nil
+
+        warn "[Herb] #{notice}" if notice
+
+        super
+      end
+    end
+  end
+end

data/lib/herb/visitor/parser_option_requirements.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+# typed: true
+
+module Herb
+  class Visitor
+    # Lets a visitor declare the parser options the AST it is handed has to carry, so that
+    # whoever parses can satisfy them before visiting.
+    #
+    #     class PrismProgramVisitor < Herb::Visitor
+    #       required_parser_option prism_program: true
+    #       recommended_parser_option strict: false
+    #     end
+    #
+    # A required option is one the visitor cannot work without, and a recommended one is a soft
+    # requirement it only works better with. `Herb::Visitor.parser_options_for` resolves both for
+    # a set of visitors, raising on a conflicting requirement and warning on a conflicting
+    # recommendation.
+    #
+    # `Herb::Visitor` includes this, so every visitor has it. Anything else that is passed to
+    # `Herb::Engine` as a visitor can include it too.
+    #
+    module ParserOptionRequirements
+      #: (untyped) -> void
+      def self.included(base)
+        super
+
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        #: (**untyped) -> void
+        def required_parser_option(**options)
+          declared_parser_options(:required).merge!(options.transform_keys(&:to_sym))
+        end
+
+        #: (**untyped) -> void
+        def recommended_parser_option(**options)
+          declared_parser_options(:recommended).merge!(options.transform_keys(&:to_sym))
+        end
+
+        #: () -> Hash[Symbol, untyped]
+        def required_parser_options
+          declared_parser_options(:required).dup
+        end
+
+        #: () -> Hash[Symbol, untyped]
+        def recommended_parser_options
+          declared_parser_options(:recommended).dup
+        end
+
+        #: (untyped) -> void
+        def inherited(subclass)
+          super
+
+          subclass.required_parser_option(**required_parser_options)
+          subclass.recommended_parser_option(**recommended_parser_options)
+        end
+
+        #: (Array[untyped], ?Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+        def parser_options_for(visitors, parser_options = {})
+          options = parser_options.transform_keys(&:to_sym)
+
+          apply_required_parser_options(visitors, options)
+          apply_recommended_parser_options(visitors, options)
+
+          options
+        end
+
+        private
+
+        #: (Array[untyped], Hash[Symbol, untyped]) -> void
+        def apply_required_parser_options(visitors, options)
+          each_declared_parser_option(visitors, :required_parser_options) do |visitor, name, value|
+            current = options[name]
+
+            if options.key?(name) && current != value
+              Kernel.raise(
+                ArgumentError,
+                "#{describe(visitor)} requires the `#{name}` parser option to be #{value.inspect}, but it is set to #{current.inspect}"
+              )
+            end
+
+            options[name] = value
+          end
+        end
+
+        #: (Array[untyped], Hash[Symbol, untyped]) -> void
+        def apply_recommended_parser_options(visitors, options)
+          each_declared_parser_option(visitors, :recommended_parser_options) do |visitor, name, value|
+            current = options[name]
+
+            unless options.key?(name)
+              options[name] = value
+
+              next
+            end
+
+            next if current == value
+
+            Kernel.warn "[Herb] #{describe(visitor)} recommends the `#{name}` parser option to be #{value.inspect}, but it is set to #{current.inspect}"
+          end
+        end
+
+        #: (Symbol) -> Hash[Symbol, untyped]
+        def declared_parser_options(kind)
+          store = @declared_parser_options ||= {} #: Hash[Symbol, Hash[Symbol, untyped]]
+
+          store[kind] ||= {}
+        end
+
+        #: (Array[untyped], Symbol) { (untyped, Symbol, untyped) -> void } -> void
+        def each_declared_parser_option(visitors, reader)
+          visitors.each do |visitor|
+            next unless visitor.respond_to?(reader)
+
+            visitor.public_send(reader).each do |name, value|
+              yield(visitor, name.to_sym, value)
+            end
+          end
+        end
+
+        #: (untyped) -> String
+        def describe(visitor)
+          visitor.class.name || visitor.class.to_s
+        end
+      end
+
+      #: () -> Hash[Symbol, untyped]
+      def required_parser_options
+        declaring_class.required_parser_options
+      end
+
+      #: () -> Hash[Symbol, untyped]
+      def recommended_parser_options
+        declaring_class.recommended_parser_options
+      end
+
+      #: (untyped) -> untyped
+      def self.class_of(object)
+        object.class
+      end
+
+      private
+
+      #: () -> untyped
+      def declaring_class
+        ParserOptionRequirements.class_of(self)
+      end
+    end
+  end
+end