[sammyapoex]

Why

An entity points at its record polymorphically (flippable_type / flippable_id), so there is no foreign key to remove it when the record is deleted. Such an entity then breaks the feature's entities page: display_entity(entity.flippable) gets nil and raises on the registered_entities.fetch("NilClass") lookup. The page cannot be opened, so the stale entity cannot be removed from the UI either.

What

The UI no longer raises on a deleted record

• Flipside.display_entity also accepts a Flipside::Entity row. A deleted record is shown as User #42 (deleted), and a record whose class is no longer registered as User #42. Both keep their remove button.

Entities are cleaned up when a record is destroyed

• New Flipside::Flippable concern with flipside_entity and flipside_role macros, so a model registers itself instead of being registered from an initializer.
• flipside_entity adds a has_many :flipside_entities, dependent: :delete_all, so destroying a record removes its entities.
• A class using the macros must be listed in Flipside.flippables. Flipside loads the listed classes on demand, so the UI finds them even when the app does not eager load. It raises if a class uses a macro without being listed, or is listed but calls neither macro.

Existing orphans can be removed

• Flipside.prune_orphaned_entities deletes entities whose record, or whose class, no longer exists, and returns how many it deleted. This covers records deleted without callbacks (delete, delete_all, SQL) and anything left over from before this change.

Smaller changes

• Registering the same role twice no longer lists it twice.
• Flipside.register_entity and Flipside.register_role are deprecated in favour of the macros and will be removed in 1.0. They still work. In a Rails 7.1+ app the warnings follow the app's own deprecation settings (Rails.application.deprecators[:flipside]).
• README: documents the macros, Flipside.flippables, registering a class from another gem through to_prepare, and upgrading from register_*. It also fixes some heading levels.
• CHANGELOG: [Unreleased] entry.

Upgrading

Nothing breaks. register_entity and register_role keep working and only warn. To move over:

# config/initializers/flipside.rb
Flipside.flippables = %w[User]

# app/models/user.rb
class User < ApplicationRecord
  include Flipside::Flippable

  flipside_entity search_by: :name, display_as: :name
  flipside_role :admin?
end

After that, run Flipside.prune_orphaned_entities once to clear out entities that were orphaned before the upgrade.

Tests

• spec/flipside/flippable_spec.rb: the macros register, destroying a record removes its entities, both flippables checks raise, and a listed class that is not loaded yet gets loaded.
• spec/flipside/web_spec.rb: the entities page renders a deleted record, with its remove form.
• spec/flipside_spec.rb: prune_orphaned_entities, the deprecation warnings, a role registered twice, and the new display_entity cases.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.