permission_forge 0.14.1 → 0.15.0

data/app/frontend/permission_forge/pf_admin.js

@@ -422,6 +422,42 @@
     }
   });
 
+  /* ------------------------------------------- rule builder preview */
+  // The preview is the sentence the saved rule shows, rendered by the server
+  // (the preview action, SentencesHelper): as the value, "the current user"
+  // or "or empty" change, the panel's content is fetched again. Field and
+  // operator changes re-render the whole builder (refresh above).
+  // Only the latest request may fill the panel: a newer input aborts the one
+  // before, so a late answer never overwrites a newer sentence. An answer that
+  // is no fragment — a redirect (a lapsed session's login page), a whole
+  // document — leaves the panel as it is: the builder's refresh and save,
+  // the no-JS path, still show the sentence.
+  let previewRequest = null;
+  function previewRule(form) {
+    const panel = form && $('[data-pf-rule-preview]', form);
+    if (!panel) return;
+    const data = new FormData(form); data.delete('authenticity_token'); data.delete('_method');
+    const base = panel.getAttribute('data-pf-rule-preview');
+    const url = base + (base.indexOf('?') < 0 ? '?' : '&') + new URLSearchParams(data).toString();
+    if (previewRequest) previewRequest.abort();
+    const request = new AbortController();
+    previewRequest = request;
+    fetch(url, { headers: { [FRAGMENT_HEADER]: '1' }, credentials: 'same-origin', signal: request.signal })
+      .then(function (res) { return res.ok && !res.redirected ? res.text() : Promise.reject(res.status); })
+      .then(function (html) {
+        if (request !== previewRequest || /<html[\s>]/i.test(html)) return;
+        setContent(panel, html);
+      })
+      .catch(function () {})
+      .then(function () { if (previewRequest === request) previewRequest = null; });
+  }
+  const previewHandler = debounce(previewRule, 250);
+  const PREVIEW_INPUTS = '[name="rule[value]"], [name="rule[values_text]"], [name="rule[values][]"], [name="rule[value_from]"], ' +
+    '[name="rule[value_to]"], [name="rule[current_user]"], [name="rule[include_nulls]"]';
+  ['input', 'change'].forEach(function (type) {
+    on(type, PREVIEW_INPUTS, function (e, el) { previewHandler(el.form); });
+  });
+
   /* ------------------------------------------- typed confirmation */
   on('input', 'input[data-pf-confirm-match]', function (e, input) {
     const btn = input.form && input.form.querySelector('[data-pf-confirm-target]');

data/app/helpers/permission_forge/application_helper.rb

@@ -4,10 +4,15 @@ module PermissionForge
     include PermissionForge::UiHelper
     include PermissionForge::BadgesHelper
     include PermissionForge::PeopleHelper
+    include PermissionForge::LabelsHelper
     include PermissionForge::SentencesHelper
+    include PermissionForge::ConditionsHelper
+    include PermissionForge::RuleProblemsHelper
     include PermissionForge::AuditSentencesHelper
     include PermissionForge::ChangesHelper
     include PermissionForge::AuditHelper
+    include PermissionForge::AuditRecordsHelper
+    include PermissionForge::AuditAttributionHelper
     include PermissionForge::SettingsHelper
 
     # Sidebar link; the current section gets aria-current="page".
@@ -54,10 +59,11 @@ module PermissionForge
       Rails.application.class.module_parent_name.to_s.titleize.presence
     end
 
+    # @deprecated Use {UiHelper#pf_relative}. Read Rails' datetime.distance_in_words keys
+    #   (English without rails-i18n); now the same as pf_relative, removed in 0.16.
     def pf_time_ago(time)
-      return t('permission_forge.shared.time_nil') if time.nil?
-
-      t('permission_forge.shared.time_ago', time: time_ago_in_words(time))
+      PermissionForge::Deprecation.warn('pf_time_ago is deprecated; use pf_relative', key: :pf_time_ago)
+      pf_relative(time)
     end
 
     def pf_available_locales
@@ -86,82 +92,26 @@ module PermissionForge
       "#{request.path}?locale=#{CGI.escape(loc)}"
     end
 
-    # Display label for a user in the assignment dropdown.
-    #
-    # Honors `config.user_label_formatter` if configured. Otherwise tries
-    # `:name`, `:full_name`, `:display_name`, then `:email`, then composes
-    # `first_name`/`last_name`, and finally falls back to `User #<id>`.
-    # The id is appended in `#<id>` form to keep labels unique.
+    # Display label for a user in the assignment dropdown: the person's
+    # label (Admin::PersonLabel — `config.user_label_formatter`, else name
+    # then email, else "User"), with the email in parentheses when the
+    # label is a name and no formatter is configured. The id is appended in
+    # `#<id>` form to keep labels unique.
     def pf_user_option_label(user)
-      formatter = PermissionForge.configuration.user_label_formatter
-      base = formatter ? formatter.call(user).to_s.strip : pf_default_user_label(user)
-      base = 'User' if base.blank?
+      label = pf_person(user)
+      return "#{t('permission_forge.shared.user')} ##{user.id}" if label.fallback?
+
+      email = label.secondary unless PermissionForge.configuration.user_label_formatter
+      base = email ? "#{label.name} (#{email})" : label.name
       "#{base} ##{user.id}"
     end
 
     private
 
-    def pf_default_user_label(user)
-      name = pf_first_present(user, :name, :full_name, :display_name) || pf_compose_name(user)
-      email = pf_raw_user_attribute(user, :email).to_s.strip.presence
-      pf_format_name_and_email(name, email)
-    end
-
-    def pf_compose_name(user)
-      [pf_raw_user_attribute(user, :first_name), pf_raw_user_attribute(user, :last_name)]
-        .compact.map { |part| part.to_s.strip }.reject(&:empty?).join(' ').presence
-    end
-
-    def pf_format_name_and_email(name, email)
-      return "#{name} (#{email})" if name && email
-      return name if name
-      return email if email
-
-      t('permission_forge.shared.user')
-    end
-
-    def pf_first_present(user, *methods)
-      methods.each do |m|
-        value = pf_raw_user_attribute(user, m).to_s.strip
-        return value unless value.empty?
-      end
-      nil
-    end
-
-    # Reads a user attribute for the admin assignment dropdown, bypassing
-    # MaskedAttributes. The dropdown is permission-management infrastructure —
-    # admins need to see user labels to assign permissions — so it must not be
-    # subject to the same field masking as ordinary reads.
-    #
-    # Real columns are read via `read_attribute_before_type_cast` FIRST: the
-    # public getter on a masked model routes every call through
-    # AttributeAccessGuard (a per-attribute permission lookup) and can hand
-    # back a masked or hidden sentinel — wrong for these labels and, across a
-    # large dropdown, the difference between milliseconds and tens of seconds.
-    # Virtual attributes (host-app methods like a composed `display_name`)
-    # still resolve via the public method, as does a column whose raw value is
-    # blank. Consequence: a host method overriding a *populated* column is not
-    # consulted here — `config.user_label_formatter` is the escape hatch for
-    # custom label logic.
+    # A user attribute for the admin's labels, read raw-column-first past
+    # MaskedAttributes (Admin::PersonLabel.raw_value: the one definition).
     def pf_raw_user_attribute(user, attr)
-      attr_name = attr.to_s
-      if pf_readable_column?(user, attr_name)
-        stored = user.read_attribute_before_type_cast(attr_name)
-        return stored if stored.to_s.strip.present?
-      end
-
-      user.try(attr)
-    end
-
-    # True when `attr_name` is a real, loaded column on an AR-like user —
-    # i.e., safe to read raw. Guards against partial SELECTs from a custom
-    # user_list_resolver, where an unloaded column must not be touched.
-    def pf_readable_column?(user, attr_name)
-      klass = user.class
-      klass.respond_to?(:column_names) &&
-        klass.column_names.include?(attr_name) &&
-        user.respond_to?(:read_attribute_before_type_cast) &&
-        (!user.respond_to?(:has_attribute?) || user.has_attribute?(attr_name))
+      Admin::PersonLabel.raw_value(user, attr)
     end
   end
 end

data/app/helpers/permission_forge/audit_attribution_helper.rb

@@ -0,0 +1,77 @@
+module PermissionForge
+  # Who created and who last edited a permission record, as the audit log
+  # names them: the one definition the footers, the Assignments tab,
+  # "Assigned by" and the audit tabs (and their CSV) use — the record's
+  # creation event (Admin::LastChanges.creations) or latest change event
+  # (Admin::LastChanges#last_edit), else the created_by / updated_by columns.
+  #
+  # @api private
+  module AuditAttributionHelper
+    # "Who · when" of an entry's creation: the creation event's actor when
+    # there is one (as the audit log names them), else created_by.
+    def pf_audit_created(entry)
+      t('permission_forge.ui.audit.who_when', who: pf_audit_entry_creator(entry), when: pf_date(entry.created_at))
+    end
+
+    # The creator of an Admin::AuditTrail entry (its creation_event is preloaded).
+    def pf_audit_entry_creator(entry)
+      event = entry.creation_event
+      event ? pf_audit_actor_name(event) : pf_person_name(entry.created_by)
+    end
+
+    # Who created a permission record, as the audit log names them — the one
+    # definition wherever the admin shows it (footers, assignment rows, the
+    # audit tabs): the actor of the record's creation event when the log has
+    # one (an HTTP Basic login or an API client stamps no created_by), else
+    # created_by, else "System". `creations` is a pf_audit_creations lookup
+    # over the page's records; without one that covers the record, the
+    # page's preloaded lookup or a lookup of its own is used.
+    def pf_audit_creator(record, creations = nil)
+      event = pf_audit_creation_event(record, creations)
+      event ? pf_audit_actor_name(event) : pf_person_name(record.try(:created_by))
+    end
+
+    # The record's creation event, or nil (see pf_audit_creator for `creations`).
+    def pf_audit_creation_event(record, creations = nil)
+      lookup = [creations, @pf_creations].find { |candidate| candidate&.covers?(record) }
+      (lookup || pf_audit_creations([record]))[record]
+    end
+
+    # The creation events of `records` in one lookup (two queries per type).
+    def pf_audit_creations(records)
+      PermissionForge::Admin::LastChanges.creations(records)
+    end
+
+    # "Who · when" of an entry's last edit: the latest change event's actor
+    # and time when there is one, else updated_by / updated_at.
+    def pf_audit_edited(entry)
+      return pf_audit_who_when(entry.updated_by, entry.updated_at, relative: true) unless entry.last_event
+
+      t('permission_forge.ui.audit.who_when', who: pf_audit_actor_name(entry.last_event), when: pf_relative(entry.updated_at))
+    end
+
+    # The record's last edit as an event (who really made it), or nil when
+    # the audit log has none for it or the record was edited after it.
+    # Uses the page's preloaded lookup when it covers the record.
+    def pf_audit_last_change(record)
+      lookup = @pf_last_changes if @pf_last_changes&.covers?(record)
+      (lookup || PermissionForge::Admin::LastChanges.new([record])).last_edit(record)
+    end
+
+    # One lookup of the edits and one of the creations (pf_audit_creator)
+    # for every footer the page shows. Nothing while the audit trail is off.
+    def pf_audit_preload_last_changes(records)
+      return unless PermissionForge.configuration.audit_trail_enabled
+
+      @pf_last_changes = PermissionForge::Admin::LastChanges.new(records)
+      @pf_creations = pf_audit_creations(records)
+      nil
+    end
+
+    # [created by, last edited by] names for the audit-trail CSV.
+    def pf_audit_people(entry)
+      edited_by = entry.last_event ? pf_audit_actor_name(entry.last_event) : pf_person_name(entry.updated_by)
+      [pf_audit_entry_creator(entry), edited_by]
+    end
+  end
+end

data/app/helpers/permission_forge/audit_helper.rb

@@ -1,139 +1,65 @@
 module PermissionForge
-  # Labels and links for audit rows (Person → Audit, Permission Set → Audit,
-  # CSV) and for audit events (the audit log, the timelines, an event).
+  # Labels for audit events (the audit log, the timelines, an event); the
+  # rows of the Audit tabs' record lists are AuditRecordsHelper's.
   #
   # @api private
   module AuditHelper
     # Every category has a glyph and a word (never colour alone).
     CATEGORY_GLYPHS = { 'change' => '✎', 'admin' => '⚑', 'system' => '⚙', 'access' => '◉' }.freeze
     CATEGORY_VARIANTS = { 'change' => :changed, 'admin' => :warn, 'system' => :default, 'access' => :mask }.freeze
-    # The message Audit::EventQuery gives a filter that needs a value (Rails' own).
-    QUERY_BLANK_MESSAGE = 'errors.messages.blank'.freeze
-    # [record label, where] per audited type; evaluated in the view context.
-    AUDIT_LABELS = {
-      'permission_set' => ->(record) { [record.name, nil] },
-      'group' => ->(record) { [record.name, nil] },
-      'resource' => ->(record) { [pf_resource_label(record), record.permission_set&.name] },
-      'field' => ->(record) { [record.label.presence || record.name, pf_audit_resource_where(record.resource)] },
-      'action' => ->(record) { [record.label.presence || record.name, pf_audit_resource_where(record.resource)] },
-      'rule' => ->(record) { [record.name, pf_audit_resource_where(record.resource)] },
-      'assignment' => ->(record) { [pf_person_name(record.user), record.permission_set&.name] },
-      'group_membership' => ->(record) { [pf_person_name(record.user), record.permission_set_group&.name] }
-    }.freeze
-
-    # Link target per audited type; evaluated in the view context.
-    AUDIT_PATHS = {
-      'permission_set' => ->(record) { permission_forge.permission_set_path(record) },
-      'resource' => ->(record) { permission_forge.permission_set_resource_path(record.permission_set_id, record.name) },
-      'field' => ->(record) { pf_audit_nested_path(record.resource, :field, record.name) },
-      'action' => ->(record) { pf_audit_nested_path(record.resource, :action, record.id) },
-      'rule' => ->(record) { pf_audit_nested_path(record.resource, :rule, record.id) },
-      'assignment' => ->(record) { permission_forge.person_path(record.user_id) },
-      'group' => ->(record) { permission_forge.group_path(record) },
-      'group_membership' => ->(record) { permission_forge.group_path(record.permission_set_group_id) }
-    }.freeze
-
-    def pf_audit_type_label(type)
-      t("permission_forge.ui.audit.types.#{type}")
-    end
-
-    # [type label, record label, where] — also used for CSV export.
-    def pf_audit_describe(entry)
-      record = entry.record
-      label, where = pf_audit_label_and_where(entry.type, record)
-      [pf_audit_type_label(entry.type), label, where]
-    end
-
-    def pf_audit_label_and_where(type, record)
-      pf_audit_lookup(AUDIT_LABELS, type, record)
-    end
-
-    def pf_audit_resource_where(resource)
-      return nil unless resource
-
-      "#{resource.permission_set&.name} › #{pf_resource_label(resource)}"
-    end
-
-    def pf_audit_path(entry)
-      pf_audit_lookup(AUDIT_PATHS, entry.type, entry.record)
-    end
-
-    # Runs the registry entry for `type` in the view context; nil for unknown types.
-    def pf_audit_lookup(registry, type, record)
-      handler = registry[type]
-      instance_exec(record, &handler) if handler
-    end
-
-    def pf_audit_nested_path(resource, kind, key)
-      return nil unless resource
-
-      case kind
-      when :field then permission_forge.permission_set_resource_field_path(resource.permission_set_id, resource.name, key)
-      when :action then permission_forge.permission_set_resource_action_path(resource.permission_set_id, resource.name, key)
-      when :rule then permission_forge.edit_permission_set_resource_rule_path(resource.permission_set_id, resource.name, key)
-      end
-    end
-
+    # The message Audit::EventQuery gives a filter that needs a value.
+    QUERY_BLANK_MESSAGE = 'permission_forge.validations.blank'.freeze
     def pf_audit_who_when(person, time, relative: false)
       t('permission_forge.ui.audit.who_when', who: pf_person_name(person),
                                               when: relative ? pf_relative(time) : pf_date(time))
     end
 
-    # "Who · when" of an entry's last edit: the latest change event's actor
-    # and time when there is one, else updated_by / updated_at.
-    def pf_audit_edited(entry)
-      return pf_audit_who_when(entry.updated_by, entry.updated_at, relative: true) unless entry.last_event
-
-      t('permission_forge.ui.audit.who_when', who: pf_audit_actor_name(entry.last_event), when: pf_relative(entry.updated_at))
-    end
+    # --- audit events ---------------------------------------------------------
 
-    # The record's last edit as an event (who really made it), or nil when
-    # the audit log has none for it or the record was edited after it.
-    # Uses the page's preloaded lookup when it covers the record.
-    def pf_audit_last_change(record)
-      lookup = @pf_last_changes if @pf_last_changes&.covers?(record)
-      (lookup || PermissionForge::Admin::LastChanges.new([record])).last_edit(record)
+    # Who acted, as recorded: the name snapshot, with what kind of actor it
+    # was when that is not a person ("ops (password prompt)", "API client").
+    # Admin::ActorLabel, the one definition.
+    def pf_audit_actor_name(event)
+      PermissionForge::Admin::ActorLabel.for(event)
     end
 
-    # One lookup for every record whose footer the page shows (two queries
-    # per record type instead of two per footer). Nothing while the audit
-    # trail is off: the footers then say so and ask nothing.
-    def pf_audit_preload_last_changes(records)
-      return unless PermissionForge.configuration.audit_trail_enabled
+    # Why, as recorded on an event (or an assignment): a reason the gem
+    # wrote itself is a code (Audit::ReasonCodes: `expired`) rendered in the
+    # page's language; any other reason as it was typed. nil when there is
+    # none. The CSV export and the API keep the stored value.
+    def pf_audit_reason(record)
+      reason = record.try(:reason).to_s.strip
+      return if reason.empty?
+      return reason unless PermissionForge::Audit::ReasonCodes.code?(reason)
 
-      @pf_last_changes = PermissionForge::Admin::LastChanges.new(records)
-      nil
+      t("permission_forge.audit_log.reason_codes.#{reason}")
     end
 
-    # [created by, last edited by] names for the audit-trail CSV.
-    def pf_audit_people(entry)
-      edited_by = entry.last_event ? pf_audit_actor_name(entry.last_event) : pf_person_name(entry.updated_by)
-      [pf_person_name(entry.created_by), edited_by]
+    # An event that named no actor (code outside a request with no
+    # PermissionForge.with_audit_actor, or an actor resolver that failed):
+    # pf_audit_actor_name reads it as the actor type "Unknown".
+    def pf_audit_unknown_actor?(event)
+      PermissionForge::Admin::ActorLabel.unknown?(event)
     end
 
-    # --- audit events ---------------------------------------------------------
-
-    # Who acted, as recorded: the name snapshot, with what kind of actor it
-    # was when that is not a person ("ops (password prompt)", "API client").
-    def pf_audit_actor_name(event)
-      type = event.actor_type.to_s
-      label = event.actor_label.presence
-      return t("permission_forge.audit_log.actor_named.#{type}", name: label, default: label) if label
-      return t('permission_forge.audit_log.person_id', id: event.actor_id) if type == 'user' && event.actor_id.present?
-
-      pf_audit_actor_type_label(type)
+    # Where "Unknown" comes from, said the same way wherever it shows (the
+    # event page, a record footer). Both already show "Unknown" as the actor
+    # right before it, so the explanation does not repeat the word.
+    def pf_audit_unknown_actor_hint
+      t('permission_forge.audit_events.show.unknown_actor_html', method: tag.code('PermissionForge.with_audit_actor'))
     end
 
+    # A type, category or source outside the catalogue is shown as stored.
     def pf_audit_actor_type_label(type)
-      t("permission_forge.audit_log.actor_types.#{type}", default: type.to_s.humanize)
+      PermissionForge::Admin::ActorLabel.type_label(type)
     end
 
     def pf_audit_category_label(category)
-      t("permission_forge.audit_log.categories.#{category}", default: category.to_s.humanize)
+      t("permission_forge.audit_log.categories.#{category}", default: category.to_s)
     end
 
     def pf_audit_source_label(source)
-      t("permission_forge.audit_log.sources.#{source}", default: source.to_s.humanize)
+      t("permission_forge.audit_log.sources.#{source}", default: source.to_s)
     end
 
     def pf_audit_category_badge(category)
@@ -173,28 +99,40 @@ module PermissionForge
     # what the event says about it.
     def pf_audit_set_name(event, lookups)
       return nil if event.permission_set_id.blank? && event.permission_set_uuid.blank?
-      return event.record_label if event.record_type == 'PermissionForge::PermissionSet' && event.record_label.present?
+      if event.record_type == 'PermissionForge::PermissionSet' && event.record_label.present?
+        return pf_record_name_text(event.record_label, :permission_set)
+      end
 
       name = lookups.permission_set_name(event)
-      return name if name
+      return pf_record_name_text(name, :permission_set) if name
 
       t('permission_forge.audit_log.deleted_set', id: event.permission_set_id || event.permission_set_uuid)
     end
 
     def pf_audit_group_name(event, lookups)
       name = lookups.group_name(event)
-      return name if name
+      return pf_record_name_text(name, :permission_set_group) if name
 
       id = PermissionForge::Admin::AuditLookups.group_id(event)
       id ? t('permission_forge.audit_log.deleted_group', id: id) : t('permission_forge.audit_log.unknown_group')
     end
 
-    # What the event is about: its label snapshot, else type and id.
+    # What the event is about: its label snapshot (a set's, group's or
+    # rule's install-default name in the page's language: Admin::RecordName),
+    # else the type's label (Admin::AuditTrail::TYPES; a class outside them
+    # as stored) and id.
     def pf_audit_record_name(event)
-      return event.record_label if event.record_label.present?
+      return pf_audit_label_text(event) if event.record_label.present?
       return '' if event.record_type.blank?
 
-      [event.record_type.to_s.demodulize.titleize, event.record_id || event.record_uuid].compact.join(' #')
+      type = PermissionForge::Admin::AuditTrail::TYPES.key(event.record_type.to_s)
+      [type ? pf_audit_type_label(type) : event.record_type.to_s, event.record_id || event.record_uuid].compact.join(' #')
+    end
+
+    # An event's record label as Admin::RecordName reads a name of its type.
+    def pf_audit_label_text(event)
+      klass = PermissionForge::ModelLookup.model_for(event.record_type.to_s) if event.record_type.to_s.start_with?('PermissionForge::')
+      klass ? pf_record_name_text(event.record_label, klass) : event.record_label
     end
 
     # A value of a before/after or snapshot table: text as it is, nothing as
@@ -202,18 +140,18 @@ module PermissionForge
     def pf_audit_value(value)
       case value
       when nil then t('permission_forge.audit_log.no_value')
-      when String then value.empty? ? t('permission_forge.audit_log.empty_text') : value
+      when String then value.empty? ? t('permission_forge.audit_log.empty_text') : pf_host_data(value)
       when true, false then t("permission_forge.audit_log.boolean.#{value}")
       when Numeric then value.to_s
-      else ActiveSupport::JSON.encode(value)
+      else pf_host_data(ActiveSupport::JSON.encode(value))
       end
     end
 
-    # One line per refused filter, in the admin's own words (EventQuery's
-    # messages are Rails' errors.messages, which a host may not translate):
-    # a value that is needed, or the value that is not valid.
+    # One line per refused filter, in the admin's own words: a value that
+    # is needed, or the value that is not valid. A filter outside the
+    # catalogue is named as stored.
     def pf_audit_filter_error(name, messages, value)
-      field = t("permission_forge.audit_events.index.filters.#{name}", default: name.to_s.humanize)
+      field = t("permission_forge.audit_events.index.filters.#{name}", default: name.to_s)
       scope = 'permission_forge.audit_events.index.invalid'
       return t("#{scope}.blank", field: field) if Array(messages).include?(I18n.t(QUERY_BLANK_MESSAGE))
       return t("#{scope}.invalid", field: field) if value.blank?

data/app/helpers/permission_forge/audit_records_helper.rb

@@ -0,0 +1,103 @@
+module PermissionForge
+  # Labels and links for the rows of the Audit tabs' record lists (Person →
+  # Audit, Permission Set → Audit, under audit_trail_enabled) and their CSV
+  # exports: each record named as the admin names it on a page, as stored in
+  # the CSV.
+  #
+  # @api private
+  module AuditRecordsHelper
+    # [record label, where] per audited type; evaluated in the view
+    # context, `csv` true for the CSV export. On a page names and labels
+    # read as everywhere else in the admin: a set's, group's or rule's
+    # install-default name in the page's language (pf_record_name), a
+    # field's or action's generated label as no label (Admin::FieldLabel,
+    # Admin::ActionLabel; a verbatim name in <code>). The CSV keeps the
+    # values as stored (an export is data, as the log's exports keep a
+    # stored reason).
+    AUDIT_LABELS = {
+      'permission_set' => ->(record, csv) { [pf_audit_name(record, csv), nil] },
+      'group' => ->(record, csv) { [pf_audit_name(record, csv), nil] },
+      'resource' => ->(record, csv) { [pf_resource_label(record), pf_audit_name(record.permission_set, csv)] },
+      'field' => lambda { |record, csv|
+        label = csv ? pf_audit_stored_label(record) : pf_field_label(record.resource&.name, record.name, row: record)
+        [label, pf_audit_resource_where(record.resource, csv)]
+      },
+      'action' => lambda { |record, csv|
+        [csv ? pf_audit_stored_label(record) : pf_audit_action_label(record), pf_audit_resource_where(record.resource, csv)]
+      },
+      'rule' => ->(record, csv) { [pf_audit_name(record, csv), pf_audit_resource_where(record.resource, csv)] },
+      'assignment' => ->(record, csv) { [pf_person_name(record.user), pf_audit_name(record.permission_set, csv)] },
+      'group_membership' => ->(record, csv) { [pf_person_name(record.user), pf_audit_name(record.permission_set_group, csv)] }
+    }.freeze
+
+    # Link target per audited type; evaluated in the view context.
+    AUDIT_PATHS = {
+      'permission_set' => ->(record) { permission_forge.permission_set_path(record) },
+      'resource' => ->(record) { permission_forge.permission_set_resource_path(record.permission_set_id, record.name) },
+      'field' => ->(record) { pf_audit_nested_path(record.resource, :field, record.name) },
+      'action' => ->(record) { pf_audit_nested_path(record.resource, :action, record.id) },
+      'rule' => ->(record) { pf_audit_nested_path(record.resource, :rule, record.id) },
+      'assignment' => ->(record) { permission_forge.person_path(record.user_id) },
+      'group' => ->(record) { permission_forge.group_path(record) },
+      'group_membership' => ->(record) { permission_forge.group_path(record.permission_set_group_id) }
+    }.freeze
+
+    def pf_audit_type_label(type)
+      t("permission_forge.ui.audit.types.#{type}")
+    end
+
+    # [type label, record label, where] of a page's row (AUDIT_LABELS).
+    def pf_audit_describe(entry, csv: false)
+      label, where = pf_audit_lookup(AUDIT_LABELS, entry.type, entry.record, csv)
+      [pf_audit_type_label(entry.type), label, where]
+    end
+
+    # [type label, record label, where] of a CSV row: stored values.
+    def pf_audit_csv_describe(entry)
+      pf_audit_describe(entry, csv: true)
+    end
+
+    # "<set> › <model>" for a row under a Resource.
+    def pf_audit_resource_where(resource, csv)
+      return nil unless resource
+
+      "#{pf_audit_name(resource.permission_set, csv)} › #{pf_resource_label(resource)}"
+    end
+
+    # A set's, group's or rule's name: as the admin names it, or as stored for the CSV.
+    def pf_audit_name(record, csv)
+      csv ? record&.name : pf_record_name(record).presence
+    end
+
+    # A field's or action's label as stored, else its name (the CSV).
+    def pf_audit_stored_label(row)
+      row.label.presence || row.name
+    end
+
+    # An action's label (Admin::ActionLabel), a verbatim key in <code>.
+    def pf_audit_action_label(action)
+      label = PermissionForge::Admin::ActionLabel.for(action)
+      label.verbatim? ? tag.code(label.text, class: 'pf-mono-key') : label.text
+    end
+
+    def pf_audit_path(entry)
+      pf_audit_lookup(AUDIT_PATHS, entry.type, entry.record)
+    end
+
+    # Runs the registry entry for `type` in the view context; nil for unknown types.
+    def pf_audit_lookup(registry, type, *)
+      handler = registry[type]
+      instance_exec(*, &handler) if handler
+    end
+
+    def pf_audit_nested_path(resource, kind, key)
+      return nil unless resource
+
+      case kind
+      when :field then permission_forge.permission_set_resource_field_path(resource.permission_set_id, resource.name, key)
+      when :action then permission_forge.permission_set_resource_action_path(resource.permission_set_id, resource.name, key)
+      when :rule then permission_forge.edit_permission_set_resource_rule_path(resource.permission_set_id, resource.name, key)
+      end
+    end
+  end
+end