crumbly 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79dd182434d2559579a926dc460606527bea5ab63bda1e1c00bcef7ecd3e221d
-  data.tar.gz: 265c0a56aa5ad03ee08d9d825b31432af7569dab24cd8d80974ed1a1e2fd2bb9
+  metadata.gz: 06aa2669dc2486a8c255ca46215e1c65e7ca3eaf76cd834501a7c0f8a1734237
+  data.tar.gz: 37ab7df264cbb31555bc2f3e646c2ea10036057dac7e9f4f70e022506906f6cf
 SHA512:
-  metadata.gz: b465f51629faefb7bfce68edeb9c8c01cb4a5b9099ecc942add8fa9ff753f3d2bccc972c6d1b19c5ef34435121b2fca127c723c5297e10343298ed389c269920
-  data.tar.gz: 39682d63dc8464e7fc3881ec95d3834f34fa1c9a1975682fa53c016e6fe105611d92d2b4f3ce784fa2792500b46e6bf59f46453c4d2fd9a71584b34ca8b8a6b3
+  metadata.gz: 5d77cc663933f726c4923fb1a5655ecff481b0eaabb6bcc0fb852306bf342e7f7838d420a68b823234fe3a13d4ea40355a500bdce8e80dc86ecb0a24788b2dc9
+  data.tar.gz: 6d3a5af07dcd0d5e69b3a6d2f6669c03c4eae29d182a17d30fa69f8f24886afd67f27d2b89e5394561f166c4033d4166d792fb4f5acca46902290b7140e6bb27

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [2.2.0] — 2026-11-06
+
+A trail class can turn off derived trails with `derive_trails false`, and a derived level labels a record without its own `to_s` "Invoice 12" instead of `#<Invoice:0x…>`.
+
+**New**
+- `derive_trails false` in a trail class, for apps that want only the trails they write, as with gretel: a view without a `breadcrumb` call gets an empty `breadcrumb_trail` and a nil `breadcrumb_json_ld`. Subclasses inherit it and `derive_trails true` turns it back on. In such a class, `Crumbly.verify!` reports a crumb that only a derived trail would read as unused, and `Crumbly::Oracle.redundant_calls` lists nothing.
+
+**Fixed**
+- A derived level whose record's model doesn't define `to_s` is labelled with the translated model name and id, "Invoice 12", instead of Ruby's `#<Invoice:0x000…>`. A model's own `to_s` still wins.
+
 ## [2.1.0] — 2026-11-06
 
 Crumbs refuse `javascript:`, `vbscript:` and `data:` URLs, and a nil record, odd bytes or `=begin` comments no longer break Crumbly.
@@ -76,7 +86,8 @@ tests. Replaces gretel: `crumbly-convert` turns its breadcrumbs files into Crumb
   `breadcrumb` calls a derived trail may now cover.
 - `Crumbly::Oracle.compare` draws trails with gretel and with Crumbly, from a test of an app migrating.
 
-[Unreleased]: https://github.com/levups/crumbly/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/levups/crumbly/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/levups/crumbly/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/levups/crumbly/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/levups/crumbly/compare/v1.1.0...v2.0.0
 [1.1.0]: https://github.com/levups/crumbly/compare/v1.0.0...v1.1.0

data/README.md

@@ -169,13 +169,14 @@ When a view doesn't call `breadcrumb`, Crumbly builds the trail from the action:
 | Action | Trail |
 |---|---|
 | `index` | the collection: your `posts` crumb if you wrote one, or else the model's plural name linked to the `index` route |
-| `show` | the record: your `post` crumb, or else its `to_s` linked to the `show` route, under the collection |
+| `show` | the record: your `post` crumb, or else its label linked to the `show` route, under the collection |
 | `new`, `create` | "New" under the collection |
 | `edit`, `update` | "Edit" under the record |
 
 The record is the one the controller has already loaded, `@post` in `PostsController`. Crumbly never runs a query
 to find it. "New" and "Edit" come from the `crumbly.new` and `crumbly.edit` translations, so you can translate
-them.
+them. A record's label is its `to_s`. A model without a `to_s` of its own gets its translated model name and id
+instead ("Post 5"), not `#<Post:0x000...>`.
 
 Nested routes work too. On `/admin/posts/5/comments`, the trail is Posts › Post 5 › Comments, and the post is
 the `@post` the controller loaded. If the controller didn't load it, Crumbly skips that level and keeps Posts.
@@ -183,6 +184,19 @@ the `@post` the controller loaded. If the controller didn't load it, Crumbly ski
 To change how these trails are built, override the private methods `collection_crumb`, `record_crumb`,
 `new_record_crumb` or `edit_record_crumb` in your trail class.
 
+To turn them off, set `derive_trails false` in the trail class. A view that doesn't call `breadcrumb` then has no
+trail, as with gretel: `breadcrumb_trail` returns `[]` and `breadcrumb_json_ld` returns `nil`.
+
+```ruby
+module Admin
+  class Breadcrumbs < Crumbly::Trail
+    derive_trails false
+  end
+end
+```
+
+Subclasses inherit the setting, and `derive_trails true` turns it back on in one of them.
+
 ### Which crumb wins
 
 Crumbly takes the first of these that applies:
@@ -194,6 +208,8 @@ Crumbly takes the first of these that applies:
 3. The trail Crumbly works out. Its parent levels follow the same rule: your crumb for the parent's model if there
    is one, or else a level Crumbly builds.
 
+With `derive_trails false`, only the first applies.
+
 ## Testing your trails
 
 Add one test:
@@ -218,7 +234,7 @@ fails when:
 - a view or another crumb calls a crumb with the wrong number of arguments (calls spread over several lines, or
   with a splat, are skipped);
 - a crumb is never used. A crumb is used when another crumb, a view or a controller calls it, when a trail
-  Crumbly works out reads it, or when it is named after a model.
+  Crumbly works out reads it (unless its class sets `derive_trails false`), or when it is named after a model.
 
 A crumb defined twice in the same class is caught even earlier: the class raises `Crumbly::DuplicateCrumb` when it
 loads.
@@ -296,6 +312,7 @@ It prints each line it left out or couldn't convert exactly, and with `--views`,
 Crumbly may now make unnecessary. It needs Prism 1.2 or later: Ruby 3.4 comes with it, and on Ruby 3.3 you add
 `gem "prism"` to the development group. While gretel is still installed on the migration branch,
 `Crumbly::Oracle` draws each trail your tests render with both gems and lists where the labels or URLs differ.
+To keep gretel's empty trail on pages whose views name no crumb, set `derive_trails false` in the trail class.
 
 The [migration guide](https://levups.github.io/crumbly/migration.html) has every step: what the converter maps to
 what, what it leaves to you, the comparison in your tests, and the same walk-through for loaf and

data/lib/crumbly/trail.rb

@@ -37,6 +37,18 @@ module Crumbly
         raise DuplicateCrumb, "#{self}##{name} is defined twice: the second definition would replace the first"
       end
 
+      def derive_trails(derive)
+        raise ArgumentError, "derive_trails takes true or false, not #{derive.inspect}" unless derive in true | false
+
+        @derive_trails = derive
+      end
+
+      def derive_trails?
+        return @derive_trails unless @derive_trails.nil?
+
+        self == Trail || superclass.derive_trails?
+      end
+
       def crumb?(name)
         trail_class = self
         while trail_class < Trail
@@ -52,6 +64,8 @@ module Crumbly
       end
 
       def derive(helpers)
+        return [] unless derive_trails?
+
         new(helpers).send(:derived_levels)
       end
     end
@@ -196,7 +210,14 @@ module Crumbly
     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)
+      crumb(record_label(record), route_path(action: "show", id: record), parent: collection_crumb)
+    end
+
+    # Kernel#to_s would label the level "#<Invoice:0x000...>".
+    def record_label(record)
+      return record.to_s unless record.class.instance_method(:to_s).owner == Kernel && record.class.respond_to?(:model_name)
+
+      "#{record.model_name.human} #{record.to_param}"
     end
 
     def new_record_crumb
@@ -235,7 +256,7 @@ module Crumbly
       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)),
+      crumb(record_label(parent.record), route_path(resources: name, action: "show", id: parent.id, **route_parent_ids(ancestors)),
         parent: nested_collection_crumb(name, ancestors))
     end
 

data/lib/crumbly/verifier.rb

@@ -165,8 +165,9 @@ module Crumbly
     end
 
     def dead_crumbs
-      reachable_names = called_names + derived_names
+      reachable_names_with_derivation = called_names + derived_names
       trail_classes.flat_map do |trail_class|
+        reachable_names = trail_class.derive_trails? ? reachable_names_with_derivation : called_names
         dead_names = crumb_names(trail_class).reject do |name|
           reachable_names.include?(name) || model_name?(name)
         end

data/lib/crumbly/version.rb

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

data/lib/crumbly/view_helpers.rb

@@ -2,7 +2,8 @@
 
 module Crumbly
   module ViewHelpers
-    # The view names its crumb; a view that says nothing gets the trail derived from its controller and action.
+    # The view names its crumb; a view that says nothing gets the trail derived from its controller and action,
+    # or none under `derive_trails false`.
     def breadcrumb(target, *arguments)
       @crumbly_breadcrumb = [target, arguments]
       @crumbly_trail = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crumbly
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Level UP Solutions