crumbly 2.0.0

data/lib/crumbly/trail.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Crumbly
+  # One subclass per namespace (Admin::Breadcrumbs < Crumbly::Trail): each public method defined there is a crumb.
+  class Trail
+    RouteParent = Data.define(:name, :id, :record)
+
+    # Included after the routes' url_helpers, whose own url_options would otherwise win.
+    module UrlOptionsFromView
+      def url_options
+        helpers.url_options
+      end
+    end
+
+    class << self
+      attr_reader :own_crumb_names
+
+      def inherited(subclass)
+        super
+        routes = Crumbly.routes
+        if routes
+          subclass.include(routes.url_helpers)
+          subclass.include(UrlOptionsFromView)
+        end
+        # Set last: including url_helpers defines methods in the subclass, which are not crumbs.
+        subclass.instance_variable_set(:@own_crumb_names, Set.new)
+      end
+
+      def method_added(name)
+        super
+        return unless own_crumb_names && public_method_defined?(name, false)
+        return if own_crumb_names.add?(name)
+
+        raise DuplicateCrumb, "#{self}##{name} is defined twice: the second definition would replace the first"
+      end
+
+      def crumb?(name)
+        trail_class = self
+        while trail_class < Trail
+          return trail_class.public_method_defined?(name) if trail_class.own_crumb_names.include?(name)
+
+          trail_class = trail_class.superclass
+        end
+        false
+      end
+
+      def resolve(helpers, target, *arguments)
+        new(helpers).send(:levels_for, target, arguments)
+      end
+
+      def derive(helpers)
+        new(helpers).send(:derived_levels)
+      end
+    end
+
+    def initialize(helpers)
+      @helpers = helpers
+    end
+
+    private
+
+    attr_reader :helpers
+
+    def crumb(label, url = nil, parent: nil, links: [])
+      Crumb.new(label:, url: path_for(url), links:, parent:)
+    end
+
+    def link(label, url)
+      Link.new(label:, url: path_for(url))
+    end
+
+    # The crumb of a record, found by its model name: `parent: crumb_for(owner)` for a polymorphic parent.
+    def crumb_for(record, *)
+      name = crumb_name_for(record)
+      return public_send(name, record, *) if name
+
+      unknown_crumb("#{self.class} has no crumb for #{record.class}: define ##{record.model_name.singular}")
+    end
+
+    def path_for(url)
+      case url
+      when nil, String then url
+      else polymorphic_path(url)
+      end
+    end
+
+    def levels_for(target, arguments)
+      levels(target_crumb(target, arguments))
+    end
+
+    def target_crumb(target, arguments)
+      return crumb_for(target, *arguments) unless target in Symbol | String
+
+      name = target.to_sym
+      return public_send(name, *arguments) if self.class.crumb?(name)
+
+      unknown_crumb("#{self.class} has no crumb named #{name}")
+    end
+
+    def levels(current_crumb)
+      return [] unless current_crumb
+
+      crumbs = []
+      crumb = current_crumb
+      while crumb
+        crumbs << crumb
+        crumb = crumb.parent
+      end
+      crumbs.reverse!
+      if self.class.crumb?(:root)
+        root_crumb = root
+        crumbs.unshift(root_crumb) unless crumbs.first == root_crumb
+      end
+
+      last_index = crumbs.size - 1
+      crumbs.each_with_index.map do |level_crumb, index|
+        Level.new(label: level_crumb.label, url: level_crumb.url, links: level_crumb.links, current: index == last_index)
+      end
+    end
+
+    # STI: a subclass without a crumb of its own falls back on its parent class's.
+    def crumb_name_for(record)
+      model_class = record.class
+      loop do
+        name = model_class.model_name.singular.to_sym
+        return name if self.class.crumb?(name)
+        return unless model_class.respond_to?(:base_class) && model_class != model_class.base_class
+
+        model_class = model_class.superclass
+      end
+    end
+
+    def unknown_crumb(message)
+      exception = UnknownCrumb.new(message)
+      raise exception if Crumbly.raise_on_unknown_crumb?
+
+      ActiveSupport.error_reporter.report(exception, handled: true)
+      nil
+    end
+
+    def controller
+      helpers.controller
+    end
+
+    def derived_levels
+      levels(derived_crumb)
+    end
+
+    def derived_crumb
+      record = controller.instance_variable_get(:"@#{controller.controller_name.singularize}")
+      case controller.action_name
+      when "index" then collection_crumb
+      when "show" then record && record_crumb(record)
+      when "new", "create" then new_record_crumb
+      when "edit", "update" then record && edit_record_crumb(record)
+      end
+    end
+
+    # The four crumbs below build a derived trail; override any of them as a private method.
+    def collection_crumb
+      nested_collection_crumb(controller.controller_name, route_parents)
+    end
+
+    def record_crumb(record)
+      return crumb_for(record) if crumb_name_for(record)
+
+      crumb(record.to_s, route_path(action: "show", id: record), parent: collection_crumb)
+    end
+
+    def new_record_crumb
+      crumb(I18n.t("crumbly.new", default: "New"), parent: collection_crumb)
+    end
+
+    def edit_record_crumb(record)
+      crumb(I18n.t("crumbly.edit", default: "Edit"), parent: record_crumb(record))
+    end
+
+    # Under a nested route (/orders/42/messages), a crumb named after the whole nesting (order_messages) is
+    # called with the parents' records; otherwise the collection is derived under its parent record.
+    def nested_collection_crumb(name, parents)
+      loaded_parents = parents.take_while(&:record)
+      if loaded_parents.size < parents.size
+        missing_parent = parents[loaded_parents.size]
+        parent = nested_collection_crumb(missing_parent.name.pluralize, loaded_parents)
+        return derived_collection_crumb(name, parents, parent:)
+      end
+
+      crumb_name = [*parents.map(&:name), name].join("_").to_sym
+      return public_send(crumb_name, *parents.map(&:record)) if self.class.crumb?(crumb_name)
+
+      derived_collection_crumb(name, parents, parent: parents.empty? ? nil : parent_record_crumb(parents))
+    end
+
+    def derived_collection_crumb(name, parents, parent:)
+      model_class = name.classify.safe_constantize
+      label = name.humanize
+      label = model_class.model_name.human(count: 2, default: label) if model_class.respond_to?(:model_name)
+      crumb(label, route_path(resources: name, action: "index", **route_parent_ids(parents)), parent:)
+    end
+
+    def parent_record_crumb(parents)
+      *ancestors, parent = parents
+      return crumb_for(parent.record) if crumb_name_for(parent.record)
+
+      name = parent.name.pluralize
+      crumb(parent.record.to_s, route_path(resources: name, action: "show", id: parent.id, **route_parent_ids(ancestors)),
+        parent: nested_collection_crumb(name, ancestors))
+    end
+
+    # The record of each :<name>_id path parameter, outermost first, as the controller loaded it (@<name>).
+    def route_parents
+      controller.request.path_parameters.filter_map do |key, value|
+        next unless key.end_with?("_id")
+
+        name = key.to_s.delete_suffix("_id")
+        RouteParent.new(name:, id: value, record: controller.instance_variable_get(:"@#{name}"))
+      end
+    end
+
+    def route_parent_ids(parents)
+      parents.to_h { |parent| [:"#{parent.name}_id", parent.id] }
+    end
+
+    # A controller without an index or show route still gets its level, without a link.
+    def route_path(resources: controller.controller_name, **options)
+      namespace = controller.controller_path.delete_suffix(controller.controller_name)
+      helpers.url_for(controller: "/#{namespace}#{resources}", only_path: true, **options)
+    rescue ActionController::UrlGenerationError
+      nil
+    end
+  end
+end

data/lib/crumbly/verifier.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Crumbly
+  class Verifier
+    BREADCRUMB_CALL = /\bbreadcrumb[\s(]+(?::(\w+)|["'](\w+)["']|@(\w+))/
+    ROUTE_HELPER = /_(?:path|url)\z/
+
+    def initialize(trail_classes:, routes:, sources:)
+      @trail_classes = trail_classes
+      @routes = routes
+      @sources = sources
+      @problems = []
+      @called_names = Set[:root]
+      @definitions_by_path = {}
+    end
+
+    def call
+      trail_classes.each { |trail_class| verify_crumbs(trail_class) }
+      verify_sources
+      raise InvalidTrail, "#{problems.size} breadcrumb problem(s):\n- #{problems.join("\n- ")}" if problems.any?
+
+      dead_crumbs
+    end
+
+    private
+
+    attr_reader :trail_classes, :routes, :sources, :problems, :called_names, :definitions_by_path
+
+    def verify_crumbs(trail_class)
+      crumb_methods = crumb_names(trail_class).map { |name| trail_class.instance_method(name) }
+      crumb_paths = crumb_methods.filter_map { |crumb_method| crumb_method.source_location&.first }
+      helper_methods = trail_class.private_instance_methods(false).map { |name| trail_class.instance_method(name) }
+      helper_methods.select! { |helper_method| crumb_paths.include?(helper_method.source_location&.first) }
+
+      (crumb_methods + helper_methods).each { |method| verify_calls(trail_class, method) }
+    end
+
+    def verify_calls(trail_class, method)
+      definition = definition_of(method)
+      return unless definition
+
+      receiverless_calls(definition).each do |call|
+        name = call.name
+        location = "#{method.source_location.first}:#{call.location.start_line}"
+        if trail_class.crumb?(name)
+          arity_problem = arity_problem(trail_class, name, call)
+          problems << "#{trail_class}##{method.name} calls #{name} #{arity_problem} (#{location})" if arity_problem
+        end
+        next if name == method.name
+
+        called_names << name
+        next if trail_class.method_defined?(name) || trail_class.private_method_defined?(name)
+
+        kind = ROUTE_HELPER.match?(name) ? "a route helper" : "a crumb"
+        problems << "#{trail_class}##{method.name} calls #{name}, which is not #{kind} (#{location})"
+      end
+    end
+
+    def definition_of(method)
+      path, line = method.source_location
+      return unless path && File.file?(path)
+
+      definitions_by_path[path] ||= definitions_in(Prism.parse_file(path).value)
+      definitions_by_path[path][[method.name, line]]
+    end
+
+    def definitions_in(tree)
+      definitions = {}
+      each_node(tree) do |node|
+        definitions[[node.name, node.location.start_line]] = node if node.is_a?(Prism::DefNode)
+      end
+      definitions
+    end
+
+    def receiverless_calls(definition)
+      calls = []
+      each_node(definition) { |node| calls << node if node in Prism::CallNode[receiver: nil] }
+      calls
+    end
+
+    def each_node(node, &block)
+      yield node
+      node.compact_child_nodes.each { |child| each_node(child, &block) }
+    end
+
+    def verify_sources
+      defined_names = trail_classes.flat_map { |trail_class| crumb_names(trail_class) }.to_set
+      source_files.each do |path|
+        File.foreach(path).with_index(1) do |line, number|
+          line.to_enum(:scan, BREADCRUMB_CALL).each do
+            match = Regexp.last_match
+            symbol, string, instance_variable = match.captures
+            name = (symbol || string || instance_variable).to_sym
+            called_names << name
+            next if instance_variable
+
+            unless defined_names.include?(name)
+              problems << "#{path}:#{number} calls breadcrumb :#{name}, which no trail defines"
+              next
+            end
+            call = breadcrumb_call(line[match.begin(0)..])
+            arity_problem = call && arity_problem(trail_classes, name, call)
+            problems << "#{path}:#{number} calls breadcrumb :#{name} #{arity_problem}" if arity_problem
+          end
+        end
+      end
+    end
+
+    # The call as Ruby, when the rest of its line parses: `breadcrumb :order, @order %>` in ERB, but not a
+    # call spread over several lines, whose arguments are left unchecked.
+    def breadcrumb_call(source)
+      parse_result = Prism.parse(source.sub(/\s*-?%>.*\z/m, ""))
+      return if parse_result.failure?
+
+      each_node(parse_result.value) do |node|
+        return node if node in Prism::CallNode[receiver: nil, name: :breadcrumb]
+      end
+      nil
+    end
+
+    # gretel ran a crumb as a block, which took any number of arguments; a crumb method raises ArgumentError.
+    def arity_problem(trail_classes, name, call)
+      arguments = call.arguments&.arguments || []
+      skipped_nodes = [Prism::SplatNode, Prism::ForwardingArgumentsNode]
+      # `breadcrumb(target, *arguments)` takes no keywords: a view's `key: value` reaches the crumb as one Hash.
+      if call.name == :breadcrumb
+        arguments = arguments.drop(1)
+      else
+        skipped_nodes << Prism::KeywordHashNode
+      end
+      return if arguments.any? { |argument| skipped_nodes.any? { |node_class| argument.is_a?(node_class) } }
+
+      crumb_methods = Array(trail_classes).filter_map do |trail_class|
+        trail_class.instance_method(name) if trail_class.crumb?(name)
+      end
+      return if crumb_methods.any? { |crumb_method| accepts?(crumb_method, arguments.size) }
+
+      "with #{arguments.size} #{"argument".pluralize(arguments.size)}, which takes #{arity(crumb_methods.first)}"
+    end
+
+    def accepts?(crumb_method, count)
+      required, optional, rest = parameter_counts(crumb_method)
+      count >= required && (rest || count <= required + optional)
+    end
+
+    def arity(crumb_method)
+      required, optional, rest = parameter_counts(crumb_method)
+      if rest then "#{required} or more"
+      elsif optional.zero? then required.to_s
+      else "#{required} to #{required + optional}"
+      end
+    end
+
+    def parameter_counts(crumb_method)
+      kinds = crumb_method.parameters.map(&:first)
+      [kinds.count(:req), kinds.count(:opt), kinds.include?(:rest)]
+    end
+
+    def source_files
+      sources.flat_map { |source| Dir.glob(File.join(source, "**", "*")) }.select { |path| File.file?(path) }
+    end
+
+    def dead_crumbs
+      reachable_names = called_names + derived_names
+      trail_classes.flat_map do |trail_class|
+        dead_names = crumb_names(trail_class).reject do |name|
+          reachable_names.include?(name) || model_name?(name)
+        end
+        dead_names.map { |name| "#{trail_class}##{name}" }
+      end
+    end
+
+    # The crumbs a derived trail reads: the collection and the record of each routed controller, and under a
+    # nested route the collection named after its nesting (order_messages for /orders/:order_id/messages).
+    def derived_names
+      return [] unless routes
+
+      routes.routes.flat_map { |route| derived_names_for(route) }.uniq
+    end
+
+    def derived_names_for(route)
+      controller_name = route.defaults[:controller]&.split("/")&.last
+      return [] unless controller_name
+
+      parent_names = route.required_parts.filter_map { |part| part.to_s.delete_suffix("_id") if part.end_with?("_id") }
+      nesting_names = (0..parent_names.size).map { |count| [*parent_names.first(count), controller_name].join("_").to_sym }
+      [*nesting_names, controller_name.singularize.to_sym]
+    end
+
+    # A crumb named after a model is reachable from any `breadcrumb @record` or `crumb_for(record)`.
+    def model_name?(name)
+      name.to_s.camelize.safe_constantize.respond_to?(:model_name)
+    end
+
+    def crumb_names(trail_class)
+      trail_class.own_crumb_names.select { |name| trail_class.public_method_defined?(name, false) }
+    end
+  end
+end

data/lib/crumbly/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Crumbly
+  VERSION = "2.0.0"
+end

data/lib/crumbly/view_helpers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Crumbly
+  module ViewHelpers
+    # The view names its crumb; a view that says nothing gets the trail derived from its controller and action.
+    def breadcrumb(target, *arguments)
+      @crumbly_breadcrumb = [target, arguments]
+      @crumbly_trail = nil
+    end
+
+    def breadcrumb_trail
+      @crumbly_trail ||= begin
+        trail_class = Crumbly.trail_class_for(controller.class)
+        if @crumbly_breadcrumb
+          target, arguments = @crumbly_breadcrumb
+          trail_class.resolve(self, target, *arguments)
+        else
+          trail_class.derive(self)
+        end
+      end
+    end
+
+    def breadcrumb_json_ld
+      breadcrumb_list = JsonLd.call(breadcrumb_trail)
+      return unless breadcrumb_list
+
+      content_tag(:script, ERB::Util.json_escape(JSON.generate(breadcrumb_list)).html_safe, type: "application/ld+json")
+    end
+  end
+end

data/lib/crumbly.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/class/subclasses"
+require "active_support/core_ext/module/introspection"
+require "active_support/core_ext/string/inflections"
+require "i18n"
+
+require_relative "crumbly/version"
+require_relative "crumbly/errors"
+require_relative "crumbly/crumb"
+require_relative "crumbly/level"
+require_relative "crumbly/trail"
+require_relative "crumbly/json_ld"
+require_relative "crumbly/controller"
+require_relative "crumbly/view_helpers"
+require_relative "crumbly/verifier"
+require_relative "crumbly/railtie" if defined?(Rails::Railtie)
+
+module Crumbly
+  class << self
+    attr_writer :routes, :raise_on_unknown_crumb, :raise_on_relative_url
+
+    def routes
+      @routes || (Rails.application&.routes if defined?(Rails.application))
+    end
+
+    def raise_on_unknown_crumb?
+      return @raise_on_unknown_crumb unless @raise_on_unknown_crumb.nil?
+
+      !production?
+    end
+
+    def raise_on_relative_url?
+      return @raise_on_relative_url unless @raise_on_relative_url.nil?
+
+      !production?
+    end
+
+    # Raises InvalidTrail with every problem found, and returns the dead crumbs ("Admin::Breadcrumbs#drafts").
+    def verify!(trail_classes: nil, routes: Crumbly.routes, sources: default_sources)
+      Rails.application.eager_load! if trail_classes.nil? && defined?(Rails.application) && Rails.application
+      Verifier.new(trail_classes: trail_classes || Trail.descendants, routes:, sources:).call
+    end
+
+    # Admin::OrdersController reads Admin::Breadcrumbs, then ::Breadcrumbs, unless it calls breadcrumbs_with.
+    def trail_class_for(controller_class)
+      explicit_trail_class = controller_class.try(:breadcrumbs_class)
+      return explicit_trail_class if explicit_trail_class
+
+      namespace = controller_class.module_parent
+      loop do
+        trail_class = namespace.const_get(:Breadcrumbs, false) if namespace.const_defined?(:Breadcrumbs, false)
+        return trail_class if trail_class.is_a?(Class) && trail_class < Trail
+        break if namespace == Object
+
+        namespace = namespace.module_parent
+      end
+      namespace = controller_class.module_parent
+      trail_class_name = (namespace == Object) ? "Breadcrumbs" : "#{namespace}::Breadcrumbs"
+      raise MissingTrail, "#{controller_class} has no breadcrumbs: define #{trail_class_name} " \
+                          "(a Crumbly::Trail) or call breadcrumbs_with in the controller"
+    end
+
+    private
+
+    def default_sources
+      return [] unless defined?(Rails.root) && Rails.root
+
+      [Rails.root.join("app/views"), Rails.root.join("app/controllers")]
+    end
+
+    def production?
+      defined?(Rails.env) && Rails.env.production?
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: crumbly
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Level UP Solutions
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: loofah
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.21'
+description: One class of plain Ruby methods per namespace, a trail derived from the
+  controller and the routes when a view says nothing, mistakes raised when the class
+  loads, and the trail returned as data for your own components.
+executables:
+- crumbly-convert
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/crumbly-convert
+- lib/crumbly.rb
+- lib/crumbly/controller.rb
+- lib/crumbly/converter.rb
+- lib/crumbly/converter/crumb_definition.rb
+- lib/crumbly/converter/source.rb
+- lib/crumbly/crumb.rb
+- lib/crumbly/derived_call_sites.rb
+- lib/crumbly/errors.rb
+- lib/crumbly/json_ld.rb
+- lib/crumbly/level.rb
+- lib/crumbly/oracle.rb
+- lib/crumbly/railtie.rb
+- lib/crumbly/test_helper.rb
+- lib/crumbly/trail.rb
+- lib/crumbly/verifier.rb
+- lib/crumbly/version.rb
+- lib/crumbly/view_helpers.rb
+homepage: https://github.com/levups/crumbly
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/levups/crumbly
+  changelog_uri: https://github.com/levups/crumbly/blob/main/CHANGELOG.md
+  documentation_uri: https://levups.github.io/crumbly/
+  bug_tracker_uri: https://github.com/levups/crumbly/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.24
+specification_version: 4
+summary: 'Breadcrumbs for Rails: namespaced, derived from your routes, checked in
+  tests'
+test_files: []