herb 0.10.4 → 0.11.0

data/lib/herb/analysis/render_graph.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "partial_declaration"
+require_relative "render_graph/ancestor_chain"
+require_relative "render_graph/call_frame"
+require_relative "render_graph/call_site_location"
+require_relative "render_graph/inferred_signature"
+require_relative "render_graph/partial_call_site"
+require_relative "render_graph/partial_context"
+require_relative "render_graph/template_roots"
+
+module Herb
+  module Analysis
+    class RenderGraph
+      MAX_ANCESTOR_CHAINS = 32 #: Integer
+
+      NO_ROOTS = TemplateRoots.new(tags: [], conditional_tags: [], renders: [], resolved: true) #: TemplateRoots
+      UNRESOLVED = PartialContext.new(chains: [], resolved: false) #: PartialContext
+      DOCUMENT_ROOT = PartialContext.new(chains: [AncestorChain::EMPTY], resolved: true) #: PartialContext
+
+      #: (Hash[String, untyped]) -> RenderGraph
+      def self.from(data)
+        call_sites = (data["callSites"] || {}).transform_values { |sites| sites.map { |site| PartialCallSite.from(site) } }
+        roots = (data["roots"] || {}).transform_values { |entry| TemplateRoots.from(entry) }
+
+        new(
+          call_sites,
+          roots,
+          Set.new(data["documentRoots"] || []),
+          data["unresolvedRenders"] || {},
+          Set.new(data["skippedFiles"] || [])
+        )
+      end
+
+      #: (?Hash[String, Array[PartialCallSite]], ?Hash[String, TemplateRoots], ?Set[String], ?Hash[String, Integer], ?Set[String]) -> void
+      def initialize(call_sites = {}, roots = {}, document_roots = Set.new, unresolved_renders = {}, skipped_files = Set.new)
+        @call_sites = call_sites
+        @roots = roots
+        @document_roots = document_roots
+        @unresolved_renders = unresolved_renders
+        @skipped_files = skipped_files
+        @contexts = {} #: Hash[String, PartialContext]
+      end
+
+      #: () -> Integer
+      def unresolved_render_count
+        @unresolved_renders.values.sum
+      end
+
+      #: () -> Integer
+      def skipped_file_count
+        @skipped_files.size
+      end
+
+      #: () -> bool
+      def complete?
+        @unresolved_renders.empty? && @skipped_files.empty?
+      end
+
+      #: (String) -> TemplateRoots
+      def roots_of(file)
+        @roots[file] || NO_ROOTS
+      end
+
+      #: (String, TemplateRoots) -> void
+      def set_roots(file, roots)
+        @roots[file] = roots
+      end
+
+      #: (String) -> Array[PartialCallSite]
+      def callers_of(partial_file)
+        @call_sites[partial_file] || []
+      end
+
+      #: (String) -> void
+      def add_document_root(file)
+        @document_roots.add(file)
+      end
+
+      #: (String) -> bool
+      def document_root?(file)
+        @document_roots.include?(file)
+      end
+
+      #: (String) -> void
+      def skip(file)
+        @skipped_files.add(file)
+      end
+
+      #: (String, Hash[String, Array[PartialCallSite]], ?Integer) -> bool
+      def replace_calls_from(caller, sites, unresolved = 0)
+        changed = replace_unresolved_from(caller, unresolved)
+
+        @call_sites.keys.each do |partial_file|
+          call_sites = @call_sites[partial_file]
+          remaining = call_sites.reject { |call_site| call_site.caller == caller }
+
+          next if remaining.size == call_sites.size
+
+          changed = true
+
+          if remaining.any?
+            @call_sites[partial_file] = remaining
+          else
+            @call_sites.delete(partial_file)
+          end
+        end
+
+        sites.each do |partial_file, call_sites|
+          next if call_sites.empty?
+
+          changed = true
+
+          @call_sites[partial_file] = callers_of(partial_file) + call_sites
+        end
+
+        @contexts.clear if changed
+
+        changed
+      end
+
+      #: (String) -> bool
+      def remove_calls_to(partial_file)
+        return false unless @call_sites.key?(partial_file)
+
+        @call_sites.delete(partial_file)
+        @contexts.clear
+
+        true
+      end
+
+      #: (String) -> InferredSignature
+      def infer_signature(partial_file)
+        callers = callers_of(partial_file)
+        names = callers.flat_map(&:locals).uniq.sort
+
+        InferredSignature.new(
+          locals: names.map { |name| StrictLocal.new(name: name, required: false, default_source: nil) },
+          call_site_count: callers.size,
+          keyword_rest: !complete?
+        )
+      end
+
+      #: (String) -> PartialContext
+      def context_of(file)
+        @contexts[file] ||= resolve_context(file, Set.new)
+      end
+
+      #: (Array[String], *String) -> Symbol
+      def descendant_verdict(files, *tag_names)
+        return :unknown if files.empty?
+
+        verdicts = files.map { |file| root_verdict(file, tag_names, Set.new) }
+
+        return :always if verdicts.all?(:always)
+        return :never if verdicts.all?(:never)
+        return :mixed if verdicts.any? { |verdict| verdict == :always || verdict == :mixed }
+
+        :unknown
+      end
+
+      #: () -> Integer
+      def size
+        @call_sites.size
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        {
+          "callSites" => @call_sites.transform_values { |sites| sites.map(&:to_h) },
+          "roots" => @roots.transform_values(&:to_h),
+          "documentRoots" => @document_roots.to_a.sort,
+          "unresolvedRenders" => @unresolved_renders,
+          "skippedFiles" => @skipped_files.to_a.sort
+        }
+      end
+
+      private
+
+      #: (String, Integer) -> bool
+      def replace_unresolved_from(caller, unresolved)
+        previous = @unresolved_renders[caller] || 0
+
+        return false if previous == unresolved
+
+        if unresolved.zero?
+          @unresolved_renders.delete(caller)
+        else
+          @unresolved_renders[caller] = unresolved
+        end
+
+        true
+      end
+
+      #: (String, Array[String], Set[String]) -> Symbol
+      def root_verdict(file, tag_names, seen)
+        return :never if seen.include?(file)
+
+        seen.add(file)
+
+        roots = roots_of(file)
+
+        return :always if roots.tags.any? { |tag| tag_names.include?(tag) }
+        return :mixed if roots.conditional_tags.any? { |tag| tag_names.include?(tag) }
+
+        through = roots.renders.map { |rendered| root_verdict(rendered, tag_names, seen.dup) }
+
+        return :always if through.include?(:always)
+        return :mixed if through.include?(:mixed)
+        return :unknown if !roots.resolved || through.include?(:unknown)
+
+        :never
+      end
+
+      #: (String, Set[String]) -> PartialContext
+      def resolve_context(file, visiting)
+        return DOCUMENT_ROOT if @document_roots.include?(file)
+        return UNRESOLVED if visiting.include?(file)
+
+        call_sites = callers_of(file)
+
+        return UNRESOLVED if call_sites.empty?
+
+        visiting.add(file)
+
+        chains = [] #: Array[AncestorChain]
+        by_key = {} #: Hash[String, AncestorChain]
+        resolved = true
+
+        call_sites.each do |call_site|
+          parent = resolve_context(call_site.caller, visiting)
+          resolved = false unless parent.resolved
+
+          frame = frame_for(call_site)
+          prefixes = parent.chains.any? ? parent.chains : [AncestorChain::EMPTY]
+
+          prefixes.each do |prefix|
+            tags = prefix.tags + call_site.ancestors
+            empty = {} #: Hash[String, String]
+            attributes = (prefix.attributes || prefix.tags.map { empty }) + (call_site.ancestor_attributes || call_site.ancestors.map { empty })
+            key = [tags, attributes].inspect
+            existing = by_key[key]
+
+            if existing
+              existing.occurrences += prefix.occurrences
+              next
+            end
+
+            if chains.size >= MAX_ANCESTOR_CHAINS
+              resolved = false
+              break
+            end
+
+            chain = AncestorChain.new(
+              tags,
+              attributes.any? { |attribute| attribute.any? } ? attributes : nil,
+              prefix.frames + [frame],
+              prefix.occurrences
+            )
+
+            by_key[key] = chain
+            chains << chain
+          end
+        end
+
+        visiting.delete(file)
+
+        PartialContext.new(chains: chains, resolved: resolved)
+      end
+
+      #: (PartialCallSite) -> CallFrame
+      def frame_for(call_site)
+        CallFrame.new(
+          file: call_site.caller,
+          ancestors: call_site.ancestors,
+          ancestor_attributes: call_site.ancestor_attributes,
+          via: call_site.via || "render",
+          location: call_site.location
+        )
+      end
+    end
+  end
+end

data/lib/herb/analysis/ruby_locals_index/local.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Herb
+  module Analysis
+    class RubyLocalsIndex
+      class Local
+        attr_reader :name #: String
+        attr_reader :declaration #: Herb::Location
+        attr_reader :usages #: Array[Herb::Location]
+
+        #: (String, Herb::Location, Array[Herb::Location]) -> void
+        def initialize(name, declaration, usages)
+          @name = name
+          @declaration = declaration
+          @usages = usages
+        end
+
+        #: () -> Array[Herb::Location]
+        def locations
+          [declaration, *usages]
+        end
+      end
+    end
+  end
+end

data/lib/herb/analysis/ruby_locals_index/named_reference.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Herb
+  module Analysis
+    class RubyLocalsIndex
+      # A name, with where it appears in the source as a byte offset and length,
+      # which is how Prism reports it.
+      class NamedReference
+        attr_reader :name #: String
+        attr_reader :start_offset #: Integer
+        attr_reader :length #: Integer
+
+        #: (String, Integer, Integer) -> void
+        def initialize(name, start_offset, length)
+          @name = name
+          @start_offset = start_offset
+          @length = length
+        end
+      end
+    end
+  end
+end

data/lib/herb/analysis/ruby_locals_index/offset_table.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Herb
+  module Analysis
+    class RubyLocalsIndex
+      # Prism reports byte offsets into the whole template while the Herb AST
+      # reports lines and 0-based character columns, so one of them has to be
+      # translated. The line table stays in bytes to index into the source, and
+      # only the column is counted in characters.
+      #
+      class OffsetTable
+        attr_reader :source #: String
+        attr_reader :line_starts #: Array[Integer]
+
+        #: (String) -> void
+        def initialize(source)
+          @source = source
+          @line_starts = [0]
+
+          source.each_byte.with_index do |byte, index|
+            @line_starts << (index + 1) if byte == 0x0A
+          end
+        end
+
+        #: (NamedReference) -> Herb::Location
+        def location_for(reference)
+          start_line, start_column = position_at(reference.start_offset)
+          end_line, end_column = position_at(reference.start_offset + reference.length)
+
+          Location.from(start_line, start_column, end_line, end_column)
+        end
+
+        #: (Integer) -> [Integer, Integer]
+        def position_at(offset)
+          following = @line_starts.bsearch_index { |start| start > offset }
+          index = following ? following - 1 : line_starts.length - 1
+          start = @line_starts[index] || 0
+
+          [index + 1, source.byteslice(start, offset - start).to_s.length]
+        end
+      end
+    end
+  end
+end

data/lib/herb/analysis/ruby_locals_index/reference_collector.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "named_reference"
+
+module Herb
+  module Analysis
+    class RubyLocalsIndex
+      class ReferenceCollector
+        attr_reader :local_reads #: Array[NamedReference]
+        attr_reader :bare_calls #: Array[NamedReference]
+        attr_reader :parameters #: Array[NamedReference]
+        attr_reader :assignments #: Array[NamedReference]
+
+        #: (Prism::Node) -> void
+        def initialize(program)
+          @local_reads = []
+          @bare_calls = []
+          @parameters = []
+          @assignments = []
+
+          walk(program)
+        end
+
+        private
+
+        #: (Prism::Node) -> void
+        def walk(node)
+          record(node)
+
+          node.compact_child_nodes.each { |child| walk(child) }
+        end
+
+        #: (Prism::Node) -> void
+        def record(node)
+          record_read(node)
+          record_binding(node)
+        end
+
+        #: (Prism::Node) -> void
+        def record_read(node)
+          case node
+          when Prism::LocalVariableReadNode
+            add(@local_reads, node.name, node.location)
+          when Prism::CallNode
+            add(@bare_calls, node.name, node.message_loc) if bare_call?(node)
+          end
+        end
+
+        #: (Prism::Node) -> void
+        def record_binding(node)
+          case node
+          when Prism::RequiredParameterNode
+            add(@parameters, node.name, node.location)
+          when Prism::OptionalParameterNode, Prism::BlockParameterNode, Prism::RestParameterNode
+            add(@parameters, node.name, node.name_loc)
+          when Prism::LocalVariableTargetNode
+            add(@assignments, node.name, node.location)
+          when Prism::LocalVariableWriteNode, Prism::LocalVariableAndWriteNode,
+               Prism::LocalVariableOrWriteNode, Prism::LocalVariableOperatorWriteNode
+            add(@assignments, node.name, node.name_loc)
+          end
+        end
+
+        #: (Prism::CallNode) -> bool
+        def bare_call?(node)
+          node.receiver.nil? && node.arguments.nil? && node.block.nil? && !node.name.to_s.end_with?("=")
+        end
+
+        #: (Array[NamedReference], Symbol?, Prism::Location?) -> void
+        def add(references, name, location)
+          return unless name && location
+
+          references << NamedReference.new(name.to_s, location.start_offset, location.length)
+        end
+      end
+    end
+  end
+end

data/lib/herb/analysis/ruby_locals_index/state_locals.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/slots/state_directives"
+
+module Herb
+  module Analysis
+    class RubyLocalsIndex
+      # Finds `herb:state` declarations so a state read indexes like a local instead of an
+      # unknown name.
+      module StateLocals
+        module_function
+
+        def locals(document, references, offsets, declared)
+          known = declared.to_h { |name, _location| [name, :seeded] }
+
+          directives(document).flat_map { |node|
+            declarations_in(node, known).map do |declaration|
+              Local.new(declaration.name, node.location, usages(declaration.name, references, offsets))
+            end
+          }
+        end
+
+        def directives(document)
+          found = [] #: Array[untyped]
+
+          walk = lambda do |node|
+            found << node if node.is_a?(Herb::AST::HerbStateDirectiveNode)
+
+            node.child_nodes.each { |child| walk.call(child) if child } if node.respond_to?(:child_nodes)
+          end
+
+          walk.call(document)
+
+          found
+        end
+
+        def declarations_in(node, known)
+          Herb::Engine::Slots::StateDirectives.parse(node, known, visitor: Herb::Engine::Slots::StateDirectives::Silent)
+        end
+
+        def usages(name, references, offsets)
+          references.bare_calls
+                    .select { |call| call.name == name || call.name == "#{name}?" }
+                    .map { |call| offsets.location_for(call) }
+        end
+      end
+    end
+  end
+end

data/lib/herb/analysis/ruby_locals_index.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "ruby_locals_index/local"
+require_relative "ruby_locals_index/state_locals"
+require_relative "ruby_locals_index/named_reference"
+require_relative "ruby_locals_index/offset_table"
+require_relative "ruby_locals_index/reference_collector"
+
+module Herb
+  module Analysis
+    class RubyLocalsIndex
+      KEYWORD_KIND = "keyword" #: String
+
+      attr_reader :locals #: Array[Local]
+      attr_reader :assignment_names #: Set[String]
+
+      #: (String) -> RubyLocalsIndex
+      def self.from_source(source)
+        document = ::Herb.parse(source, prism_program: true, strict_locals: true, herb_directives: true).value
+
+        from_document(document, source)
+      end
+
+      #: (Herb::AST::DocumentNode, String) -> RubyLocalsIndex
+      def self.from_document(document, source)
+        program = document.deserialized_prism_node
+
+        return new([]) unless program
+
+        offsets = OffsetTable.new(source)
+        references = ReferenceCollector.new(program)
+
+        new(
+          strict_locals(document, references, offsets) +
+            block_locals(document, references, offsets) +
+            StateLocals.locals(document, references, offsets, declarations(document)),
+          references.assignments.to_set(&:name)
+        )
+      end
+
+      #: (Array[Local], ?Set[String]) -> void
+      def initialize(locals, assignment_names = Set.new)
+        @locals = locals
+        @assignment_names = assignment_names
+      end
+
+      #: (Integer, Integer) -> Local?
+      def at(line, column)
+        candidates = @locals.select do |local|
+          local.locations.any? { |location| self.class.covers?(location, line, column) }
+        end
+
+        candidates.min do |a, b|
+          self.class.encloses?(b.declaration, a.declaration) ? -1 : 1
+        end
+      end
+
+      #: (String) -> Local?
+      def find(name)
+        @locals.find { |local| local.name == name }
+      end
+
+      # Every name the template binds, regardless of where.
+      #: () -> Set[String]
+      def names
+        @locals.to_set(&:name)
+      end
+
+      #: (Herb::Location, Integer, Integer) -> bool
+      def self.covers?(location, line, column)
+        return false if line < location.start.line || line > location.end.line
+        return false if line == location.start.line && column < location.start.column
+        return false if line == location.end.line && column > location.end.column
+
+        true
+      end
+
+      #: (Herb::Location, Herb::Location) -> bool
+      def self.encloses?(outer, inner)
+        covers?(outer, inner.start.line, inner.start.column) && covers?(outer, inner.end.line, inner.end.column)
+      end
+
+      #: (Herb::AST::DocumentNode, ReferenceCollector, OffsetTable) -> Array[Local]
+      def self.strict_locals(document, references, offsets)
+        declarations(document).map do |name, location|
+          usages = references.bare_calls.select { |call| call.name == name }.map { |call| offsets.location_for(call) }
+
+          Local.new(name, location, usages)
+        end
+      end
+
+      #: (Herb::AST::DocumentNode) -> Array[[String, Herb::Location]]
+      def self.declarations(document)
+        document.children.flat_map do |child|
+          next [] unless child.is_a?(AST::ERBStrictLocalsNode)
+
+          child.locals.to_a.filter_map { |local| declaration_for(local) }
+        end
+      end
+
+      #: (Herb::AST::Node) -> [String, Herb::Location]?
+      def self.declaration_for(local)
+        return nil unless local.is_a?(AST::RubyParameterNode)
+        return nil unless local.kind == KEYWORD_KIND
+
+        name = local.name&.value
+        start = local.name&.location&.start
+
+        return nil unless name && start
+
+        [name, Location.from(start.line, start.column, start.line, start.column + name.length)]
+      end
+
+      #: (Herb::AST::DocumentNode, ReferenceCollector, OffsetTable) -> Array[Local]
+      def self.block_locals(document, references, offsets)
+        blocks = block_locations(document)
+
+        (references.parameters + references.assignments).map do |reference|
+          location = offsets.location_for(reference)
+          scope = innermost_enclosing(blocks, location)
+
+          Local.new(reference.name, location, reads_in_scope(reference, references, offsets, scope))
+        end
+      end
+
+      #: (NamedReference, ReferenceCollector, OffsetTable, Herb::Location?) -> Array[Herb::Location]
+      def self.reads_in_scope(reference, references, offsets, scope)
+        references
+          .local_reads
+          .select { |read| read.name == reference.name }
+          .map { |read| offsets.location_for(read) }
+          .select { |usage| scope.nil? || encloses?(scope, usage) }
+      end
+
+      #: (Herb::AST::DocumentNode) -> Array[Herb::Location]
+      def self.block_locations(document)
+        found = [] #: Array[Herb::Location]
+
+        walk = lambda do |node|
+          found << node.location if block_node?(node) && node.location
+
+          node.compact_child_nodes.each { |child| walk.call(child) }
+        end
+
+        walk.call(document)
+
+        found
+      end
+
+      #: (Herb::AST::Node) -> bool
+      def self.block_node?(node)
+        node.is_a?(AST::ERBBlockNode) || node.is_a?(AST::ERBIterationBlockNode)
+      end
+
+      #: (Array[Herb::Location], Herb::Location) -> Herb::Location?
+      def self.innermost_enclosing(locations, inner)
+        locations.select { |location| encloses?(location, inner) }.min { |a, b| encloses?(b, a) ? -1 : 1 }
+      end
+
+      private_class_method :strict_locals, :declarations, :declaration_for, :block_locals, :reads_in_scope, :block_locations, :block_node?, :innermost_enclosing
+    end
+  end
+end