crumbly 2.0.0

data/lib/crumbly/converter.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "prism"
+require "crumbly"
+require_relative "converter/source"
+require_relative "converter/crumb_definition"
+
+if Gem::Version.new(Prism::VERSION) < Gem::Version.new("1.2")
+  raise LoadError, "crumbly-convert needs prism 1.2 or later (#{Prism::VERSION} is loaded): add gem \"prism\" " \
+                   "to your Gemfile"
+end
+
+module Crumbly
+  # Turns gretel's breadcrumbs files into one Crumbly::Trail subclass, and lists what it leaves out.
+  class Converter
+    Result = Data.define(:ruby, :notes)
+
+    Note = Data.define(:path, :line, :message) do
+      def to_s
+        "#{path}:#{line}: #{message}"
+      end
+    end
+
+    class Unconvertible < StandardError
+      attr_reader :line
+
+      def initialize(message, line)
+        super(message)
+        @line = line
+      end
+    end
+
+    Definition = Data.define(:key, :path, :line, :lines)
+
+    STATIC_NODES = [
+      Prism::SymbolNode, Prism::StringNode, Prism::IntegerNode, Prism::FloatNode,
+      Prism::NilNode, Prism::TrueNode, Prism::FalseNode, Prism::ConstantReadNode, Prism::ConstantPathNode
+    ].freeze
+    LoopValue = Data.define(:source, :text)
+
+    def self.call(source_by_path, namespace: nil)
+      new(source_by_path, namespace:).call
+    end
+
+    def initialize(source_by_path, namespace:)
+      unless namespace.nil? || namespace.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
+        raise ArgumentError, "#{namespace.inspect} is not a module name"
+      end
+
+      @source_by_path = source_by_path
+      @namespace = namespace
+      @entries = []
+      @definition_by_key = {}
+      @notes = []
+      @helper_methods = []
+    end
+
+    def call
+      source_by_path.each do |path, text|
+        source = Source.parse(text, path:)
+        convert_statements(source.statements, source)
+        trailing_comments = source.comment_lines(source.statements.last&.location&.end_offset || 0, text.bytesize)
+        entries << trailing_comments if trailing_comments.any?
+      end
+      Result.new(ruby: render, notes: notes.sort_by { |note| [note.path, note.line] })
+    end
+
+    private
+
+    attr_reader :source_by_path, :namespace, :entries, :definition_by_key, :notes, :helper_methods
+
+    # A crumb becomes a method, which cannot see the locals assigned around it: each one it reads is copied in.
+    def convert_statements(statements, source, local_by_name = {})
+      previous_end_offset = source.start_offset
+      statements.each do |statement|
+        comments = source.comment_lines(previous_end_offset, statement.location.start_offset)
+        previous_end_offset = statement.location.end_offset
+        convert_statement(statement, source, comments, local_by_name)
+      rescue Unconvertible => exception
+        note(source, exception.line, exception.message)
+      end
+    end
+
+    def convert_statement(statement, source, comments, local_by_name)
+      if crumb_call?(statement)
+        define(CrumbDefinition.new(statement, source, local_by_name:), source, comments)
+      elsif statement.is_a?(Prism::LocalVariableWriteNode)
+        if local_by_name.key?(statement.name)
+          note(source, statement.location.start_line, "#{statement.name} is assigned again: a crumb above that " \
+                                                      "reads it gets its first value, where gretel read the last one")
+        end
+        local = CrumbDefinition::Local.new(node: statement, source:)
+        helper_methods << comments + local.method_lines if local.helper_method?
+        local_by_name[statement.name] = local
+      elsif loop_call?(statement)
+        entries << comments if comments.any?
+        expand_loop(statement, source, local_by_name)
+      else
+        raise Unconvertible.new("not a crumb definition, left out: #{summary(statement)}",
+          statement.location.start_line)
+      end
+    end
+
+    def crumb_call?(node)
+      node in Prism::CallNode[receiver: nil, name: :crumb]
+    end
+
+    def loop_call?(node)
+      node in Prism::CallNode[name: :each | :each_pair, receiver: Prism::Node, block: Prism::BlockNode]
+    end
+
+    def define(crumb_definition, source, comments)
+      key = crumb_definition.key
+      lines = comments + crumb_definition.lines
+      crumb_definition.notes.uniq.each { |message| note(source, crumb_definition.line, message) }
+      line = crumb_definition.line
+
+      if (previous = definition_by_key[key])
+        entries.delete(previous)
+        notes << Note.new(path: previous.path, line: previous.line,
+          message: "crumb :#{key} is defined again on #{source.path}:#{line}, which gretel kept: left out")
+      end
+      definition = Definition.new(key:, path: source.path, line:, lines:)
+      definition_by_key[key] = definition
+      entries << definition
+    end
+
+    def expand_loop(call, source, local_by_name)
+      block = call.block
+      parameters = loop_parameters(block)
+      unless parameters
+        raise Unconvertible.new("crumbs defined in a loop whose block takes #{block.parameters&.slice.inspect}: " \
+                                "left out, write them by hand", call.location.start_line)
+      end
+
+      bindings = literal_bindings(call.receiver, parameters, call.name)
+      unless bindings
+        raise Unconvertible.new("crumbs defined in a loop over #{summary(call.receiver)}, which is not a literal: " \
+                                "left out, write them by hand", call.location.start_line)
+      end
+
+      start_offset = block.parameters ? block.parameters.location.end_offset : block.opening_loc.end_offset
+      bindings.each do |value_by_name|
+        text = source.rewrite(start_offset, block.closing_loc.start_offset, substitutions(block.body, value_by_name))
+        expansion = value_by_name.map { |name, value| "#{name} = #{value.source}" }.join(", ")
+        expanded_source = source.expansion(text, start_offset, expansion, local_by_name.keys)
+        convert_statements(expanded_source.statements, expanded_source, local_by_name.dup)
+      end
+    end
+
+    # A parameter destructured by the block (`|name, (parent, label)|`) is an array of names.
+    def loop_parameters(block)
+      parameters = block.parameters&.parameters
+      return unless parameters in {optionals: [], rest: nil, posts: [], keywords: [], keyword_rest: nil, block: nil}
+
+      parameters.requireds.map { |parameter| loop_parameter(parameter) || (return nil) }
+    end
+
+    def loop_parameter(parameter)
+      case parameter
+      when Prism::RequiredParameterNode then parameter.name
+      when Prism::MultiTargetNode
+        return unless parameter.rest.nil? && parameter.rights.empty?
+
+        parameter.lefts.map { |left| loop_parameter(left) || (return nil) }
+      end
+    end
+
+    # The value of each parameter, for each element: Ruby splats what the loop yields over several parameters,
+    # or over a single destructured one.
+    def literal_bindings(collection, parameters, method_name)
+      collection = collection.receiver while collection.is_a?(Prism::CallNode) && collection.name == :freeze
+      return unless static?(collection)
+
+      single_name = parameters.first if parameters.size == 1 && parameters.first.is_a?(Symbol)
+      case collection
+      when Prism::ArrayNode
+        return if method_name == :each_pair
+
+        collection.elements.map do |element|
+          next {single_name => loop_value(element)} if single_name
+
+          bind(parameters, element.is_a?(Prism::ArrayNode) ? element.elements : [element])
+        end
+      when Prism::HashNode
+        collection.elements.map do |association|
+          pair = [association.key, association.value]
+          next bind(parameters, pair) unless single_name
+
+          {single_name => LoopValue.new(source: "[#{pair.map { |node| loop_value(node).source }.join(", ")}]", text: nil)}
+        end
+      end
+    end
+
+    def bind(parameters, values, value_by_name = {})
+      parameters = parameters.first if parameters.size == 1 && parameters.first.is_a?(Array)
+      parameters.each_with_index do |parameter, index|
+        value = values[index]
+        if parameter.is_a?(Symbol)
+          value_by_name[parameter] = value ? loop_value(value) : LoopValue.new(source: "nil", text: nil)
+        else
+          bind(parameter, value.is_a?(Prism::ArrayNode) ? value.elements : [value].compact, value_by_name)
+        end
+      end
+      value_by_name
+    end
+
+    def static?(node)
+      case node
+      when Prism::ArrayNode then node.elements.all? { |element| static?(element) }
+      when Prism::HashNode
+        node.elements.all? do |element|
+          element.is_a?(Prism::AssocNode) && static?(element.key) && static?(element.value)
+        end
+      else STATIC_NODES.any? { |node_class| node.is_a?(node_class) }
+      end
+    end
+
+    def loop_value(node)
+      case node
+      when Prism::SymbolNode then LoopValue.new(source: node.unescaped.to_sym.inspect, text: node.unescaped)
+      when Prism::StringNode then LoopValue.new(source: node.unescaped.inspect, text: node.unescaped)
+      else LoopValue.new(source: node.slice, text: nil)
+      end
+    end
+
+    def substitutions(node, value_by_name, depth = 0, edits = [])
+      case node
+      when Prism::LocalVariableReadNode
+        value = value_by_name[node.name] if node.depth == depth
+        edits << [node.location.start_offset, node.location.end_offset, value.source] if value
+        return edits
+      when Prism::CallNode
+        if (node in {name: :to_s, arguments: nil, receiver: Prism::LocalVariableReadNode[depth: ^depth, name:]}) &&
+            (text = value_by_name[name]&.text)
+          return edits << [node.location.start_offset, node.location.end_offset, text.inspect]
+        end
+      when Prism::EmbeddedStatementsNode
+        if node in {statements: {body: [Prism::LocalVariableReadNode[depth: ^depth, name:]]}}
+          text = value_by_name[name]&.text
+          if text&.match?(%r{\A[\w ./-]*\z})
+            edits << [node.location.start_offset, node.location.end_offset, text]
+            return edits
+          end
+        end
+      when Prism::BlockNode, Prism::LambdaNode then depth += 1
+      when Prism::DefNode then return edits
+      end
+      node&.compact_child_nodes&.each { |child| substitutions(child, value_by_name, depth, edits) }
+      edits
+    end
+
+    def note(source, line, message)
+      message += " (#{source.expansion_description})" if source.expansion_description
+      notes << Note.new(path: source.path, line:, message:)
+    end
+
+    def summary(node)
+      first_line = node.slice.lines.first.strip
+      (first_line.length > 60) ? "#{first_line[0, 57]}..." : first_line
+    end
+
+    def render
+      modules = namespace.to_s.split("::")
+      depth = modules.size
+      body = entries.map do |entry|
+        lines = entry.is_a?(Definition) ? entry.lines : entry
+        indent(lines, depth + 1).join("\n")
+      end
+
+      ruby = +"# frozen_string_literal: true\n\n"
+      modules.each_with_index { |name, index| ruby << "#{"  " * index}module #{name}\n" }
+      ruby << "#{"  " * depth}class Breadcrumbs < Crumbly::Trail\n"
+      if helper_methods.any?
+        body << "#{"  " * (depth + 1)}private"
+        body.concat(helper_methods.map { |lines| indent(lines, depth + 1).join("\n") })
+      end
+      ruby << body.join("\n\n") << "\n" if body.any?
+      ruby << "#{"  " * depth}end\n"
+      depth.downto(1) { |index| ruby << "#{"  " * (index - 1)}end\n" }
+      ruby
+    end
+
+    def indent(lines, depth)
+      lines.map { |line| line.empty? ? line : "#{"  " * depth}#{line}" }
+    end
+  end
+end

data/lib/crumbly/crumb.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Crumbly
+  Link = Data.define(:label, :url)
+
+  Crumb = Data.define(:label, :url, :links, :parent)
+end

data/lib/crumbly/derived_call_sites.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "crumbly"
+
+module Crumbly
+  # Lists the `breadcrumb` calls of views whose trail the action now derives, for a person to review: a call
+  # is only redundant when the derived trail matches the one its crumb drew.
+  module DerivedCallSites
+    CallSite = Data.define(:path, :line, :code, :reason) do
+      def to_s
+        "#{path}:#{line}: #{code} (#{reason})"
+      end
+    end
+
+    BREADCRUMB_CALL = /\bbreadcrumb[ (]\s*(?<target>:\w+|@\w+)(?<arguments>[^\n%}]*)/
+    VIEW_GLOB = "**/*.{erb,haml,slim,ruby}"
+    FORM_CRUMBS = %w[generic_form new edit].freeze
+
+    def self.call(*directories)
+      directories.flat_map do |directory|
+        Dir.glob(VIEW_GLOB, base: directory).sort.flat_map { |path| call_sites(File.join(directory, path)) }
+      end
+    end
+
+    def self.call_sites(path)
+      action = File.basename(path).split(".").first
+      controller_name = File.basename(File.dirname(path))
+      File.foreach(path).with_index(1).filter_map do |line, number|
+        match = BREADCRUMB_CALL.match(line)
+        reason = match && reason(match[:target], match[:arguments].strip.delete_suffix(")").strip, action, controller_name)
+        CallSite.new(path:, line: number, code: match[0].strip, reason:) if reason
+      end
+    end
+
+    def self.reason(target, arguments, action, controller_name)
+      record = "@#{controller_name.singularize}"
+      if FORM_CRUMBS.include?(target.delete_prefix(":"))
+        case action
+        when "new" then 'new derives "New" under the collection'
+        when "edit" then 'edit derives "Edit" under the record'
+        else "only new and edit views derive a form's trail"
+        end
+      elsif action == "show" && (target == record || (target == ":#{controller_name.singularize}" && arguments == ", #{record}"))
+        "show derives the crumb of #{record}"
+      elsif action == "index" && target == ":#{controller_name}" && arguments.empty?
+        "index derives the #{controller_name} crumb"
+      end
+    end
+  end
+end

data/lib/crumbly/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Crumbly
+  class Error < StandardError; end
+
+  class DuplicateCrumb < Error; end
+
+  class UnknownCrumb < Error; end
+
+  class MissingTrail < Error; end
+
+  class InvalidTrail < Error; end
+
+  class RelativeUrl < Error; end
+end

data/lib/crumbly/json_ld.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/filters"
+require "active_support/core_ext/string/output_safety"
+require "json"
+require "loofah"
+
+module Crumbly
+  # A schema.org BreadcrumbList, as Google's Rich Results test reads it.
+  module JsonLd
+    ABSOLUTE_URL_PREFIXES = ["https://", "http://"].freeze
+
+    class << self
+      def call(levels)
+        list_items = []
+        levels.each do |level|
+          # Google requires an item on every ListItem but the last: a level without a page is left out.
+          next unless level.url || level.current?
+
+          list_item = {"@type" => "ListItem", "position" => list_items.size + 1, "name" => plain_text(level.label)}
+          if level.url
+            return relative_url(level) unless level.url.start_with?(*ABSOLUTE_URL_PREFIXES)
+
+            list_item["item"] = level.url
+          end
+          list_items << list_item
+        end
+        return if list_items.empty?
+
+        {"@context" => "https://schema.org", "@type" => "BreadcrumbList", "itemListElement" => list_items}
+      end
+
+      private
+
+      def plain_text(label)
+        return label.to_s.squish unless label.html_safe?
+
+        Loofah.html5_fragment(label).scrub!(:prune).text(encode_special_chars: false).squish
+      end
+
+      def relative_url(level)
+        exception = RelativeUrl.new("JSON-LD needs absolute URLs: #{plain_text(level.label).inspect} links to " \
+                                    "#{level.url}, use a _url helper in its crumb")
+        raise exception if Crumbly.raise_on_relative_url?
+
+        ActiveSupport.error_reporter.report(exception, handled: true)
+        nil
+      end
+    end
+  end
+end

data/lib/crumbly/level.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Crumbly
+  Level = Data.define(:label, :url, :links, :current) do
+    def current?
+      current
+    end
+  end
+end

data/lib/crumbly/oracle.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "gretel"
+require "crumbly"
+
+module Crumbly
+  # Compares gretel's trail with Crumbly's for the same crumbs, from a test of an app that still bundles gretel.
+  module Oracle
+    Difference = Data.define(:target, :arguments, :gretel, :crumbly, :page) do
+      def initialize(target:, arguments:, gretel:, crumbly:, page: nil)
+        super
+      end
+
+      def to_s
+        call = target ? "breadcrumb #{Oracle.format_call(target, arguments)}" : "no breadcrumb call"
+        "#{"#{page}, " if page}#{call}\n" \
+          "  gretel:     #{format_trail(gretel)}\n" \
+          "  crumbly: #{format_trail(crumbly)}"
+      end
+
+      private
+
+      def format_trail(trail)
+        return "(none)" if trail.empty?
+
+        trail.map { |label, url| url ? "#{label} (#{url})" : label }.join(" > ")
+      end
+    end
+
+    RedundantCall = Data.define(:page, :target, :arguments) do
+      def to_s
+        "#{page}, breadcrumb #{Oracle.format_call(target, arguments)}: the action derives the same trail"
+      end
+    end
+
+    # Prepended to the view helpers by `watch`: each page the tests render compares its trail with gretel's.
+    module Watch
+      def breadcrumb_trail
+        return super if @crumbly_trail || !Oracle.watching?
+
+        levels = super
+        Oracle.observe(self, @crumbly_breadcrumb, levels)
+        levels
+      end
+    end
+
+    @differences = Set.new
+    @redundant_calls = Set.new
+    @mutex = Mutex.new
+    @watching = false
+
+    class << self
+      attr_reader :differences, :redundant_calls
+
+      # `cases` lists what views pass to `breadcrumb`: `[[:orders], [:order, order], [order]]`.
+      def compare(view, trail_class, cases)
+        ::Gretel::Crumbs.reload_if_needed
+        cases.filter_map do |target, *arguments|
+          gretel = gretel_trail(view, target, arguments)
+          crumbly = crumbly_trail(view, trail_class, target, arguments)
+          Difference.new(target:, arguments:, gretel:, crumbly:) unless gretel == crumbly
+        end
+      end
+
+      # From then on, or for the block, each trail a view renders is compared with the one gretel draws for its
+      # `breadcrumb` call (nothing, without one). The differences go to `differences`, and the calls whose trail
+      # the action derives anyway to `redundant_calls`.
+      def watch
+        ViewHelpers.prepend(Watch) unless ViewHelpers <= Watch
+        watching = @watching
+        @watching = true
+        return unless block_given?
+
+        begin
+          yield
+        ensure
+          @watching = watching
+        end
+      end
+
+      def watching?
+        @watching
+      end
+
+      def observe(view, breadcrumb_call, levels)
+        ::Gretel::Crumbs.reload_if_needed
+        target, arguments = breadcrumb_call
+        page = "#{view.controller.controller_path}##{view.controller.action_name}"
+        gretel = target ? gretel_trail_or_error(view, target, arguments) : []
+        difference = Difference.new(target:, arguments:, gretel:, crumbly: flatten(levels), page:)
+        redundant = target && derived_trail(view) == gretel
+        @mutex.synchronize do
+          differences << difference unless difference.gretel == difference.crumbly
+          redundant_calls << RedundantCall.new(page:, target:, arguments:) if redundant
+        end
+      end
+
+      # gretel renders each link of a crumb as a level of its own; Crumbly keeps the extra ones in `links`.
+      def gretel_trail(view, target, arguments)
+        links = []
+        crumb = ::Gretel::Crumb.new(view, target, *arguments)
+        while crumb
+          links.unshift(*crumb.links)
+          crumb = crumb.parent
+        end
+        if links.none? { |link| link.key == :root } && ::Gretel::Crumbs.crumb_defined?(:root)
+          links.unshift(*::Gretel::Crumb.new(view, :root).links)
+        end
+        links.map { |link| [link.text.to_s, link.url] }
+      end
+
+      def crumbly_trail(view, trail_class, target, arguments)
+        flatten(trail_class.resolve(view, target, *arguments))
+      end
+
+      def format_call(target, arguments)
+        [target, *arguments].map { |argument| format_argument(argument) }.join(", ")
+      end
+
+      private
+
+      # A call gretel cannot draw (a crumb renamed during the migration) is a difference, not a failing test.
+      def gretel_trail_or_error(view, target, arguments)
+        gretel_trail(view, target, arguments)
+      rescue => exception
+        [["gretel raised #{exception.class}: #{exception.message}", nil]]
+      end
+
+      def flatten(levels)
+        levels.flat_map do |level|
+          [[level.label.to_s, level.url], *level.links.map { |link| [link.label.to_s, link.url] }]
+        end
+      end
+
+      # A derived trail that raises (an action loading no record, say) only means the call has to stay.
+      def derived_trail(view)
+        flatten(Crumbly.trail_class_for(view.controller.class).derive(view))
+      rescue
+        nil
+      end
+
+      def format_argument(argument)
+        argument.respond_to?(:model_name) ? "#<#{argument.class.name} #{argument.to_param}>" : argument.inspect
+      end
+    end
+  end
+end

data/lib/crumbly/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Crumbly
+  class Railtie < Rails::Railtie
+    initializer "crumbly.helpers" do
+      ActiveSupport.on_load(:action_controller_base) { include Crumbly::Controller }
+      ActiveSupport.on_load(:action_view) { include Crumbly::ViewHelpers }
+    end
+  end
+end

data/lib/crumbly/test_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "crumbly"
+
+module Crumbly
+  module TestHelper
+    def assert_breadcrumbs_valid(**options)
+      dead_crumbs = Crumbly.verify!(**options)
+      assert_empty dead_crumbs, "Dead crumbs, called by no crumb, view or controller: #{dead_crumbs.join(", ")}"
+    rescue InvalidTrail => exception
+      flunk exception.message
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_support_test_case) { include Crumbly::TestHelper }