herb 0.10.4 → 0.11.0

data/lib/herb/analysis/partial_declaration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Herb
+  module Analysis
+    StrictLocal = Data.define(:name, :required, :default_source)
+
+    class StrictLocal
+      #: (name: String, required: bool, ?default_source: String?) -> void
+      def initialize(name:, required:, default_source: nil)
+        super
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        serialized = { "name" => name, "required" => required }
+        serialized["defaultSource"] = default_source if default_source
+        serialized
+      end
+
+      #: (Hash[String, untyped]) -> StrictLocal
+      def self.from(data)
+        new(name: data["name"], required: data["required"], default_source: data["defaultSource"])
+      end
+    end
+
+    class PartialDeclaration
+      KEYWORD_KIND = "keyword" #: String
+      KEYWORD_REST_KIND = "keyword_rest" #: String
+
+      attr_reader :file #: String
+      attr_reader :locals #: Array[StrictLocal]
+      attr_reader :location #: Hash[String, Integer]?
+
+      attr_accessor :has_declaration #: bool
+      attr_accessor :has_keyword_rest #: bool
+
+      #: (String) -> PartialDeclaration
+      def self.without_strict_locals(file)
+        new(file)
+      end
+
+      #: (Herb::AST::DocumentNode, String) -> PartialDeclaration
+      def self.from_document(document, file)
+        declaration = without_strict_locals(file)
+
+        document.children.each do |child|
+          next unless child.is_a?(AST::ERBStrictLocalsNode)
+
+          declaration.has_declaration = true
+          declaration.location ||= location_of(child)
+
+          child.locals&.each do |local|
+            next unless local.is_a?(AST::RubyParameterNode)
+
+            if local.kind == KEYWORD_REST_KIND
+              declaration.has_keyword_rest = true
+              next
+            end
+
+            next unless local.kind == KEYWORD_KIND
+
+            name = local.name&.value
+
+            declaration.add_local(name, local.required, default_source: local.default_value&.content) if name
+          end
+        end
+
+        declaration
+      end
+
+      #: (Herb::AST::Node) -> Hash[String, Integer]?
+      def self.location_of(node)
+        start = node.location&.start
+
+        return nil unless start
+
+        { "line" => start.line, "column" => start.column }
+      end
+
+      #: (Hash[String, untyped]) -> PartialDeclaration
+      def self.from(data)
+        declaration = new(data["file"])
+        declaration.has_declaration = data["hasDeclaration"] || false
+        declaration.has_keyword_rest = data["hasKeywordRest"] || false
+        declaration.location = data["location"]
+
+        (data["locals"] || []).each do |local|
+          declaration.add_local(local["name"], local["required"], default_source: local["defaultSource"])
+        end
+
+        declaration
+      end
+
+      #: (String) -> void
+      def initialize(file)
+        @file = file
+        @has_declaration = false
+        @has_keyword_rest = false
+        @locals = [] #: Array[StrictLocal]
+        @location = nil
+      end
+
+      #: (Hash[String, Integer]?) -> void
+      attr_writer :location
+
+      #: (String, bool, ?default_source: String?) -> void
+      def add_local(name, required, default_source: nil)
+        @locals << StrictLocal.new(name: name, required: required, default_source: default_source)
+      end
+
+      #: () -> Array[String]
+      def required_locals
+        @locals.select(&:required).map(&:name)
+      end
+
+      #: () -> Array[String]
+      def optional_locals
+        @locals.reject(&:required).map(&:name)
+      end
+
+      #: (String) -> bool
+      def accepts?(local_name)
+        return true if @has_keyword_rest
+        return true unless @has_declaration
+
+        @locals.any? { |local| local.name == local_name }
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        {
+          "file" => @file,
+          "hasDeclaration" => @has_declaration,
+          "hasKeywordRest" => @has_keyword_rest,
+          "locals" => @locals.map(&:to_h)
+        }.tap { |hash| hash["location"] = @location if @location }
+      end
+    end
+  end
+end

data/lib/herb/analysis/partial_index.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "partial_declaration"
+require_relative "partial_resolution"
+
+module Herb
+  module Analysis
+    class PartialIndex
+      APPLICATION_DIRECTORY = "application" #: String
+
+      attr_reader :view_root #: Pathname
+
+      attr_reader :templates #: Array[String]
+
+      #: (String | Pathname, ?templates: Array[String]?) -> PartialIndex
+      def self.build(project_path, templates: nil)
+        root = Pathname.new(project_path)
+        view_root = resolve_view_root(root)
+        files = templates || Dir[view_root.join("**", PartialResolution::TEMPLATE_GLOB_PATTERN)].sort
+
+        new(view_root, files)
+      end
+
+      #: (String | Pathname) -> Pathname
+      def self.resolve_view_root(project_path)
+        PartialResolution.view_root_for(project_path)
+      end
+
+      #: (String | Pathname, Array[String]) -> void
+      def initialize(view_root, templates)
+        @view_root = Pathname.new(view_root)
+        @templates = templates
+        @by_name = build_index(templates)
+        @declarations = {} #: Hash[String, PartialDeclaration?]
+      end
+
+      #: (String?) -> Array[String]
+      def files_for(partial_name)
+        return [] unless partial_name
+
+        @by_name[partial_name] || []
+      end
+
+      #: (String?, String?) -> Array[String]
+      def resolve(partial_name, source_file)
+        return [] unless partial_name
+
+        exact = files_for(partial_name)
+
+        return exact if exact.any?
+
+        if source_file
+          relative = source_directory_for(source_file)
+
+          if relative && relative != "."
+            sibling = files_for("#{relative}/#{partial_name}")
+
+            return sibling if sibling.any?
+          end
+        end
+
+        return [] if partial_name.include?("/")
+
+        files_for("#{APPLICATION_DIRECTORY}/#{partial_name}")
+      end
+
+      #: (String, String | Pathname) -> String?
+      def self.partial_name_for(file, view_root)
+        PartialResolution.partial_name_for(file, view_root)
+      end
+
+      #: (String) -> String?
+      def partial_name_for(file)
+        self.class.partial_name_for(file, @view_root)
+      end
+
+      #: () -> Array[String]
+      def names
+        @by_name.keys
+      end
+
+      #: (String?, String?) -> PartialDeclaration?
+      def lookup(partial_name, source_file)
+        file = resolve(partial_name, source_file).first
+
+        return nil unless file
+
+        declaration_for_file(file)
+      end
+
+      #: (String) -> PartialDeclaration?
+      def declaration_for_file(file)
+        @declarations[file] ||= build_declaration(file)
+      end
+
+      #: (String) -> String?
+      def update(file)
+        name = partial_name_for(file)
+
+        return nil unless name
+
+        @declarations.delete(file)
+        @templates = (@templates | [file]).sort
+
+        files = (@by_name[name] || []) | [file]
+        @by_name[name] = PartialResolution.by_precedence(files)
+
+        name
+      end
+
+      #: (String) -> String?
+      def remove(file)
+        name = partial_name_for(file)
+
+        return nil unless name
+
+        @declarations.delete(file)
+        @templates = @templates - [file]
+
+        files = (@by_name[name] || []) - [file]
+
+        if files.empty?
+          @by_name.delete(name)
+        else
+          @by_name[name] = files
+        end
+
+        name
+      end
+
+      #: () -> Integer
+      def size
+        @by_name.size
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        partials = {} #: Hash[String, untyped]
+
+        names.sort.each do |name|
+          declaration = lookup(name, nil)
+
+          partials[name] = declaration.to_h if declaration
+        end
+
+        { "viewRoot" => @view_root.to_s, "partials" => partials }
+      end
+
+      private
+
+      #: (String) -> String?
+      def source_directory_for(source_file)
+        Pathname.new(File.dirname(source_file)).relative_path_from(@view_root).to_s
+      rescue ArgumentError
+        nil
+      end
+
+      #: (String) -> PartialDeclaration?
+      def build_declaration(file)
+        return nil unless File.exist?(file)
+
+        source = File.read(file)
+        document = ::Herb.parse(source, strict_locals: true).value
+
+        PartialDeclaration.from_document(document, file)
+      rescue StandardError
+        PartialDeclaration.without_strict_locals(file)
+      end
+
+      #: (Array[String]) -> Hash[String, Array[String]]
+      def build_index(files)
+        map = {} #: Hash[String, Array[String]]
+
+        files.each do |file|
+          name = partial_name_for(file)
+
+          next unless name
+
+          (map[name] ||= []) << file
+        end
+
+        map.each_value { |files| files.replace(PartialResolution.by_precedence(files)) }
+        map
+      end
+    end
+  end
+end

data/lib/herb/analysis/partial_resolution.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Herb
+  module Analysis
+    module PartialResolution
+      PARTIAL_PREFIX = "_" #: String
+
+      EXTENSIONS = [
+        ".html.erb",
+        ".html.herb",
+        ".erb",
+        ".herb",
+        ".turbo_stream.erb",
+        ".turbo_stream.herb"
+      ].freeze #: Array[String]
+
+      EXTENSION_ALTERNATIVES = EXTENSIONS.map { |extension| extension.delete_prefix(".") }.join(",") #: String
+
+      TEMPLATE_GLOB_PATTERN = "*.{#{EXTENSION_ALTERNATIVES}}".freeze #: String
+      PARTIAL_GLOB_PATTERN = "#{PARTIAL_PREFIX}#{TEMPLATE_GLOB_PATTERN}".freeze #: String
+
+      VIEW_ROOT = File.join("app", "views") #: String
+
+      LAYOUTS_DIRECTORY = "layouts" #: String
+      APPLICATION_LAYOUT = "application" #: String
+      MAILER_LAYOUT = "mailer" #: String
+      MAILER_SUFFIX = "_mailer" #: String
+
+      class << self
+        #: (String | Pathname) -> Pathname
+        def view_root_for(project_path)
+          root = project_path.is_a?(Pathname) ? project_path : Pathname.new(project_path)
+
+          candidates = [
+            root.join(VIEW_ROOT),
+            root
+          ]
+
+          candidates.find(&:directory?) || root
+        end
+
+        #: (String) -> bool
+        def template_path?(file)
+          name = File.basename(file)
+
+          EXTENSIONS.any? { |extension| name.end_with?(extension) }
+        end
+
+        #: (String) -> bool
+        def partial_path?(file)
+          name = File.basename(file)
+
+          return false unless name.start_with?(PARTIAL_PREFIX)
+
+          EXTENSIONS.any? { |extension| name.end_with?(extension) }
+        end
+
+        #: (String) -> Integer
+        def template_rank(file)
+          basename = File.basename(file)
+          dot = basename.index(".")
+
+          return EXTENSIONS.size unless dot
+
+          rank = EXTENSIONS.index(basename[dot..])
+
+          rank || EXTENSIONS.size
+        end
+
+        #: (String, String) -> bool
+        def outranks_template?(candidate, incumbent)
+          candidate_rank = template_rank(candidate)
+          incumbent_rank = template_rank(incumbent)
+
+          return candidate_rank < incumbent_rank unless candidate_rank == incumbent_rank
+
+          candidate < incumbent
+        end
+
+        #: (Array[String]) -> Array[String]
+        def by_precedence(files)
+          files.sort { |a, b| outranks_template?(a, b) ? -1 : 1 }
+        end
+
+        #: (String, String | Pathname) -> String?
+        def template_name_for(file, view_root)
+          return nil if partial_path?(file)
+
+          relative = relative_to_view_root(file, view_root)
+
+          return nil unless relative
+
+          directory = File.dirname(relative)
+          name = File.basename(relative).sub(/\..*\z/, "")
+
+          return nil if name.empty?
+
+          directory == "." ? name : "#{directory}/#{name}"
+        end
+
+        #: (String, String | Pathname) -> Array[String]
+        def layout_candidates_for(template_file, view_root)
+          relative = relative_to_view_root(template_file, view_root)
+
+          return [] unless relative
+          return [] if File.basename(relative).start_with?(PARTIAL_PREFIX)
+
+          directory = File.dirname(relative)
+
+          return [] if directory == LAYOUTS_DIRECTORY || directory.start_with?("#{LAYOUTS_DIRECTORY}/")
+          return ["#{LAYOUTS_DIRECTORY}/#{APPLICATION_LAYOUT}"] if directory == "." || directory == "/"
+
+          segments = directory.split("/")
+          mailer = segments.last.end_with?(MAILER_SUFFIX)
+          candidates = [] #: Array[String]
+
+          until segments.empty?
+            candidates << "#{LAYOUTS_DIRECTORY}/#{segments.join("/")}"
+            segments.pop
+          end
+
+          candidates << "#{LAYOUTS_DIRECTORY}/#{mailer ? MAILER_LAYOUT : APPLICATION_LAYOUT}"
+
+          candidates
+        end
+
+        #: (String, String | Pathname) -> String?
+        def partial_name_for(file, view_root)
+          return nil unless partial_path?(file)
+
+          relative = relative_to_view_root(file, view_root)
+
+          return nil unless relative
+
+          directory = File.dirname(relative)
+          name = File.basename(relative).delete_prefix(PARTIAL_PREFIX).sub(/\..*\z/, "")
+
+          return nil if name.empty?
+
+          directory == "." ? name : "#{directory}/#{name}"
+        end
+
+        private
+
+        #: (String, String | Pathname) -> String?
+        def relative_to_view_root(file, view_root)
+          root = view_root.is_a?(Pathname) ? view_root : Pathname.new(view_root)
+          relative = Pathname.new(file).relative_path_from(root).to_s
+
+          return nil if relative == "." || relative.start_with?("..")
+
+          relative
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/herb/analysis/partial_resolver.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+# typed: true
+
+require "did_you_mean"
+require "pathname"
+
+require_relative "partial_resolution"
+
+module Herb
+  module Analysis
+    # Finds the file a render call names, and what the compile of that file calls itself.
+    #
+    # The engine resolves partials at compile time in more than one place, the render
+    # validator and the inliner among them, and each used to walk the filesystem on its own
+    # from the project's view root. This is the one object they ask instead, and the one an
+    # application can replace through `Herb::Engine.new(source, resolver: ...)` with a lookup
+    # that knows its real view paths, an engine's or a gem's, and how it names its templates.
+    #
+    # The default answers from the filesystem the way the engine always has. A name with a
+    # directory is looked up under the view root, a bare name next to the calling template
+    # and then under the view root, and the identifier is the path relative to the project,
+    # which is what the compile of that template reports as its own relative file path.
+    #
+    class PartialResolver
+      Resolved = Data.define(
+        :path,      #: Pathname
+        :identifier #: String
+      )
+
+      TEMPLATE_HINT = "exists as a template, not a partial. Rename to" #: String
+
+      attr_reader :project_path #: Pathname
+      attr_reader :view_root #: Pathname?
+
+      #: (?(String | Pathname)?, ?view_root: (String | Pathname | false)?) -> void
+      def initialize(project_path = nil, view_root: nil)
+        @project_path = Pathname.new(project_path || Dir.pwd)
+        @view_root = case view_root
+                     when false then nil
+                     when nil then PartialResolution.view_root_for(@project_path)
+                     else Pathname.new(view_root)
+                     end
+      end
+
+      #: (String, ?from: (String | Pathname)?, ?format: String?) -> Resolved?
+      def resolve(name, from: nil, format: nil)
+        paths = candidates(name, from: from)
+        paths = prefer_format(paths, format) if format
+        path = paths.find(&:exist?)
+
+        return nil unless path
+
+        Resolved.new(path: path, identifier: identifier_for(path))
+      end
+
+      #: (String, ?from: (String | Pathname)?) -> Array[Pathname]
+      def candidates(name, from: nil)
+        candidate_paths(name, source_directory(from))
+      end
+
+      #: (String, ?from: (String | Pathname)?, ?limit: Integer) -> Array[String]
+      def similar(name, from: nil, limit: 3)
+        similar_partials(name, source_directory(from), limit: limit)
+      end
+
+      #: (Pathname) -> String
+      def identifier_for(path)
+        path.relative_path_from(project_path).to_s
+      rescue ArgumentError
+        path.to_s
+      end
+
+      #: (String, Pathname?) -> Array[Pathname]
+      def candidate_paths(name, source_directory)
+        directories = lookup_directories(name, source_directory)
+        base = File.basename(name)
+
+        PartialResolution::EXTENSIONS.flat_map do |extension|
+          directories.map { |directory| directory.join("_#{base}#{extension}") }
+        end
+      end
+
+      #: (String, Pathname?, ?limit: Integer) -> Array[String]
+      def similar_partials(name, source_directory, limit: 3)
+        names = partial_names(source_directory)
+        suggestions = DidYouMean::SpellChecker.new(dictionary: names).correct(name).first(limit)
+
+        suggestions.empty? ? non_partial_matches(name, source_directory) : suggestions
+      end
+
+      #: (String, Pathname?) -> Array[String]
+      def non_partial_matches(name, source_directory)
+        directories = lookup_directories(name, source_directory)
+        base = File.basename(name)
+
+        PartialResolution::EXTENSIONS.filter_map do |extension|
+          next unless directories.any? { |directory| directory.join("#{base}#{extension}").exist? }
+
+          "#{name}#{extension} #{TEMPLATE_HINT} _#{base}#{extension} to use it with render"
+        end
+      end
+
+      private
+
+      #: (String, Pathname?) -> Array[Pathname]
+      def lookup_directories(name, source_directory)
+        root = view_root
+
+        return [source_directory, root].compact unless name.include?("/")
+
+        root ? [root.join(File.dirname(name))] : []
+      end
+
+      #: (Pathname?) -> Array[String]
+      def partial_names(source_directory)
+        root = view_root
+        directory = root || source_directory
+
+        return [] unless directory&.directory?
+
+        pattern = root ? File.join(root, "**", PartialResolution::PARTIAL_GLOB_PATTERN) : File.join(directory, PartialResolution::PARTIAL_GLOB_PATTERN)
+
+        Dir[pattern].filter_map { |file| PartialResolution.partial_name_for(file, directory) }.uniq
+      end
+
+      #: ((String | Pathname)?) -> Pathname?
+      def source_directory(from)
+        return nil unless from
+
+        file = Pathname.new(from)
+        file = project_path + file unless file.absolute?
+
+        file.dirname
+      end
+
+      #: (Array[Pathname], String) -> Array[Pathname]
+      def prefer_format(paths, format)
+        preferred, rest = paths.partition { |path| path.basename.to_s.include?(".#{format}.") }
+
+        preferred + rest
+      end
+    end
+  end
+end