paper_view 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b12547320bb6d8dd78354092beee8c80f6fe2936e7476ef766791c7fdd2caa2
+  data.tar.gz: 35aef5e07fbf35d80559c57e961ad7b388aaee2de8ca7d16e0f6c8279f48d096
+SHA512:
+  metadata.gz: 5771770579c64ff7442fbbfdea10a9b071917e45c2e0ecda1cd8fa8e30d8c461eaa21ffa85bf81fa389a9e507ac7bebcf831cdc3a41990224aa69ae45eb201ef
+  data.tar.gz: e4129deda604f38f7c862ebf8afa45e1b4b2bc18930ed747f647170e76b3dda48080562940041990939bc056e67b3bf8400d71cc7cac2325710dadbebfe75f45

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Leon
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# PaperView
+
+A lightweight, mountable dashboard for [paper_trail](https://github.com/paper-trail-gem/paper_trail).
+Browse the `versions` table and read, in one chronological timeline, what actually changed.   
+
+## Installation
+
+### 1. Add the gem
+
+```ruby
+# Gemfile
+gem "paper_view"
+```
+
+### 2. Mount the engine
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  authenticate :user, ->(user) { user.admin? } do
+    mount PaperView::Engine => "/paper_view"
+  end
+end
+```
+
+### 3. Configure it (optional)
+
+```ruby
+# config/initializers/paper_view.rb
+PaperView.setup do |config|
+  # Inherit from your own controller so that Devise/Pundit/layout helpers are available.
+  config.parent_controller = "ApplicationController"
+
+  # Runs as a before_action, evaluated inside the controller instance.
+  config.authenticate_with { redirect_to main_app.root_path unless current_user&.admin? }
+
+  # Must return a truthy value, otherwise the request is answered with 403.
+  config.authorize_with { current_user.admin? }
+
+  # Turn `whodunnit` into something readable.
+  config.whodunnit_label = ->(whodunnit) { User.find_by(id: whodunnit)&.email || whodunnit }
+
+  # Any strftime format.
+  config.time_format = "%Y-%m-%d %H:%M:%S"
+
+  config.per_page = 25
+
+  # Any model with the paper_trail column layout works here.
+  # Required interface: id, item_type, item_id, event, whodunnit, created_at, object_changes
+  config.version_class_name = "PaperTrail::Version"
+end
+```
+
+Visit `/paper_view`.

data/app/controllers/paper_view/application_controller.rb

@@ -0,0 +1,22 @@
+module PaperView
+  class ApplicationController < PaperView.config.parent_controller.constantize
+    layout "paper_view/application"
+
+    before_action :authenticate_paper_view!
+    before_action :authorize_paper_view!
+
+    private
+
+    def authenticate_paper_view!
+      block = PaperView.config.authentication_block
+      instance_exec(&block) if block
+    end
+
+    def authorize_paper_view!
+      block = PaperView.config.authorization_block
+      return if block.nil?
+
+      head :forbidden unless instance_exec(&block)
+    end
+  end
+end

data/app/controllers/paper_view/versions_controller.rb

@@ -0,0 +1,12 @@
+module PaperView
+  class VersionsController < ApplicationController
+    def index
+      @query = VersionQuery.new(params)
+      @item_types = @query.item_types
+      return unless @query.submitted?
+
+      @paginator = Paginator.new(@query.relation, page: params[:page], per_page: params[:per_page].presence || PaperView.config.per_page)
+      @timeline = Timeline.new(@paginator.records, selected_id: params[:version])
+    end
+  end
+end

data/app/helpers/paper_view/application_helper.rb

@@ -0,0 +1,37 @@
+module PaperView
+  module ApplicationHelper
+    EMPTY = "—".freeze
+
+    def paper_view_whodunnit(version)
+      label = PaperView.config.whodunnit_label
+      value = label ? label.call(version.whodunnit) : version.whodunnit
+      value.presence || EMPTY
+    end
+
+    def paper_view_time(time)
+      return EMPTY if time.nil?
+
+      tag.time(time.strftime(PaperView.config.time_format), datetime: time.iso8601, title: time.iso8601)
+    end
+
+    def paper_view_item_path(version)
+      versions_path(item_type: version.item_type, item_id: version.item_id)
+    end
+
+    def paper_view_filter_params(overrides = {})
+      request.query_parameters.except("page", "version").merge(overrides)
+    end
+
+    def paper_view_hidden_filters(except: [])
+      excluded = Array(except).map(&:to_s)
+      safe_join(paper_view_filter_params.except(*excluded).map { |name, value| hidden_field_tag(name, value, id: nil) })
+    end
+
+    def paper_view_nonce_attribute
+      nonce = content_security_policy_nonce
+      return unless nonce
+
+      raw(%( nonce="#{h(nonce)}"))
+    end
+  end
+end

data/app/models/paper_view/attribute_change.rb

@@ -0,0 +1,127 @@
+require "json"
+
+module PaperView
+  class AttributeChange
+    JSON_START = /\A\s*[\[{]/
+
+    attr_reader :name, :old_value, :new_value
+
+    def self.display(value, pretty: false)
+      case value
+      when nil then EMPTY
+      when String then value.empty? ? '""' : value
+      when Hash, Array then json(value, pretty: pretty)
+      when Time then value.in_time_zone.strftime(PaperView.config.time_format)
+      else value.to_s
+      end
+    end
+
+    def self.json(value, pretty: false)
+      pretty ? JSON.pretty_generate(value) : JSON.generate(value)
+    rescue
+      value.inspect
+    end
+
+    def self.structure(value)
+      case value
+      when Hash, Array then value
+      when String then parse(value)
+      end
+    end
+
+    def self.parse(text)
+      return unless text.match?(JSON_START)
+
+      structure = JSON.parse(text)
+      structure if structure.is_a?(Hash) || structure.is_a?(Array)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Walks both sides at once, collecting every leaf as a [path, old, new] triple.
+    # Arrays line up by index while their length holds. Once it changes they compare by
+    # membership instead, each gone or gained element labelled with its own position.
+    def self.flatten_pair(old_value, new_value, path = nil, target = [])
+      if both(Hash, old_value, new_value)
+        (old_value.keys | new_value.keys).each do |key|
+          flatten_pair(old_value[key], new_value[key], [path, key].compact.join("."), target)
+        end
+      elsif both(Array, old_value, new_value) && old_value.size == new_value.size
+        old_value.each_index { |index| flatten_pair(old_value[index], new_value[index], "#{path}[#{index}]", target) }
+      elsif both(Array, old_value, new_value)
+        old_value.each_with_index { |item, index| target << ["#{path}[#{index}]", item, new_value.include?(item) ? item : nil] }
+        new_value.each_with_index { |item, index| target << ["#{path}[#{index}]", nil, item] unless old_value.include?(item) }
+      else
+        target << [path, old_value, new_value]
+      end
+      target
+    end
+
+    def self.both(kind, old_value, new_value)
+      old_value.is_a?(kind) && new_value.is_a?(kind) && (old_value.any? || new_value.any?)
+    end
+
+    def initialize(name, old_value, new_value)
+      @name = name.to_s
+      @old_value = old_value
+      @new_value = new_value
+    end
+
+    def nested?
+      !structures.nil?
+    end
+
+    def old_text
+      @old_text ||= text(old_value)
+    end
+
+    def new_text
+      @new_text ||= text(new_value)
+    end
+
+    def leaf_changes
+      leaf_pairs.filter_map { |path, before, after| LeafChange.new(path, before, after) if before != after }
+    end
+
+    def unchanged_count
+      leaf_pairs.count { |_, before, after| before == after }
+    end
+
+    def leaves
+      return [LeafChange.new(name, old_value, new_value)] unless nested?
+
+      leaf_changes.map { |change| change.under(name) }
+    end
+
+    private
+
+    def text(value)
+      self.class.display(self.class.structure(value) || value, pretty: true)
+    end
+
+    def structures
+      return @structures if defined?(@structures)
+
+      @structures = structure_pair
+    end
+
+    # Both sides have to be the same kind of structure. A blank side counts as an empty one,
+    # so a structure that was just set or cleared still diffs.
+    def structure_pair
+      pair = [old_value, new_value].map { |value| self.class.structure(value) }
+      kind = pair.compact.first&.class
+      return unless kind && pair.any? { |structure| structure&.any? }
+
+      pair = pair.zip([old_value, new_value]).map { |structure, value| structure || (kind.new if blank?(value)) }
+      pair if pair.all? { |structure| structure.is_a?(kind) }
+    end
+
+    def blank?(value)
+      value.nil? || value == ""
+    end
+
+    def leaf_pairs
+      @leaf_pairs ||= nested? ? self.class.flatten_pair(*structures) : []
+    end
+  end
+end

data/app/models/paper_view/change_set.rb

@@ -0,0 +1,48 @@
+module PaperView
+  class ChangeSet
+    include Enumerable
+
+    def self.for(version)
+      payload = raw_payload(version)
+      changes = Payload.parse(payload)
+      new(changes || {}, raw: payload, unreadable: changes.nil? && payload.present?)
+    end
+
+    def self.raw_payload(version)
+      version.object_changes if version.respond_to?(:object_changes)
+    rescue
+      nil
+    end
+
+    attr_reader :entries, :raw
+
+    def initialize(raw_changes, raw: nil, unreadable: false)
+      @raw = raw
+      @unreadable = unreadable
+      @entries = raw_changes.filter_map do |name, pair|
+        next unless pair.is_a?(Array) && pair.size == 2
+        AttributeChange.new(name, pair.first, pair.last)
+      end
+    end
+
+    def unreadable?
+      @unreadable
+    end
+
+    def each(&block)
+      entries.each(&block)
+    end
+
+    def empty?
+      entries.empty?
+    end
+
+    def size
+      entries.size
+    end
+
+    def raw_text
+      @raw_text ||= raw.is_a?(Hash) ? AttributeChange.json(raw, pretty: true) : raw.to_s
+    end
+  end
+end

data/app/models/paper_view/leaf_change.rb

@@ -0,0 +1,29 @@
+module PaperView
+  class LeafChange
+    attr_reader :path, :old_value, :new_value
+
+    def initialize(path, old_value, new_value)
+      @path = path.to_s
+      @old_value = old_value
+      @new_value = new_value
+    end
+
+    def under(prefix)
+      self.class.new(prefixed(prefix), old_value, new_value)
+    end
+
+    def prefixed(prefix)
+      return prefix if path.empty?
+
+      path.start_with?("[") ? "#{prefix}#{path}" : "#{prefix}.#{path}"
+    end
+
+    def old_text
+      AttributeChange.display(old_value)
+    end
+
+    def new_text
+      AttributeChange.display(new_value)
+    end
+  end
+end

data/app/models/paper_view/paginator.rb

@@ -0,0 +1,61 @@
+module PaperView
+  class Paginator
+    WINDOW = 2
+    PER_PAGE_OPTIONS = [25, 50, 100, 500].freeze
+
+    attr_reader :page, :per_page, :total_count
+
+    def initialize(relation, page:, per_page:)
+      @relation = relation
+      @per_page = per_page.to_i.clamp(1, 200)
+      @total_count = relation.count(:all)
+      @page = page.to_i.clamp(1, [total_pages, 1].max)
+    end
+
+    def per_page_options
+      (PER_PAGE_OPTIONS + [per_page]).uniq.sort
+    end
+
+    def records
+      @records ||= @relation.offset(offset).limit(per_page).to_a
+    end
+
+    def total_pages
+      (total_count / per_page.to_f).ceil
+    end
+
+    def offset
+      (page - 1) * per_page
+    end
+
+    def first_page?
+      page <= 1
+    end
+
+    def last_page?
+      page >= total_pages
+    end
+
+    def previous_page
+      first_page? ? nil : page - 1
+    end
+
+    def next_page
+      last_page? ? nil : page + 1
+    end
+
+    def page_numbers
+      return [] if total_pages <= 1
+
+      candidates = [1, total_pages]
+      ((page - WINDOW)..(page + WINDOW)).each do |number|
+        candidates << number if number.between?(1, total_pages)
+      end
+
+      candidates.uniq.sort.each_with_object([]) do |number, list|
+        list << :gap if list.last.is_a?(Integer) && number > list.last + 1
+        list << number
+      end
+    end
+  end
+end

data/app/models/paper_view/payload.rb

@@ -0,0 +1,95 @@
+require "json"
+require "psych"
+
+module PaperView
+  class Payload
+    SYMBOL_TAGS = ["!ruby/symbol", "!ruby/sym", "tag:yaml.org,2002:symbol"].freeze
+    BIG_DECIMAL_TAG = "!ruby/object:BigDecimal".freeze
+    TIME_WITH_ZONE_TAG = "!ruby/object:ActiveSupport::TimeWithZone".freeze
+
+    def self.parse(raw)
+      return raw if raw.is_a?(Hash)
+      return nil if raw.blank?
+
+      text = raw.to_s
+      json(text) || new(text).to_h
+    end
+
+    def self.json(text)
+      parsed = JSON.parse(text)
+      parsed if parsed.is_a?(Hash)
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    def initialize(text)
+      @text = text
+      @anchors = {}
+      @scanner = Psych::ScalarScanner.new(Psych::ClassLoader.new)
+    end
+
+    def to_h
+      document = Psych.parse(@text)
+      value = document && visit(document.root)
+      value if value.is_a?(Hash)
+    rescue Psych::Exception
+      nil
+    end
+
+    private
+
+    def visit(node)
+      case node
+      when Psych::Nodes::Mapping then mapping(node)
+      when Psych::Nodes::Sequence then sequence(node)
+      when Psych::Nodes::Scalar then register(node, scalar(node))
+      when Psych::Nodes::Alias then @anchors[node.anchor]
+      end
+    end
+
+    def mapping(node)
+      pairs = {}
+      register(node, pairs)
+      node.children.each_slice(2) { |key, value| pairs[visit(key).to_s] = visit(value) }
+      (node.tag == TIME_WITH_ZONE_TAG) ? time_with_zone(pairs) : pairs
+    end
+
+    def time_with_zone(pairs)
+      utc = pairs["utc"]
+      return pairs unless utc.is_a?(Time)
+
+      zone = pairs.dig("zone", "name")
+      (zone && Time.find_zone(zone)&.at(utc)) || utc
+    end
+
+    def sequence(node)
+      items = []
+      register(node, items)
+      node.children.each { |child| items << visit(child) }
+      items
+    end
+
+    def scalar(node)
+      return node.value if node.quoted
+      return @scanner.tokenize(node.value) if node.tag.nil?
+
+      case node.tag
+      when *SYMBOL_TAGS then node.value.to_sym
+      when BIG_DECIMAL_TAG then big_decimal(node.value)
+      else node.value
+      end
+    end
+
+    def big_decimal(value)
+      number = value.split(":", 2).last
+      defined?(BigDecimal) ? BigDecimal(number) : number
+    rescue ArgumentError, TypeError
+      number
+    end
+
+    def register(node, value)
+      @anchors[node.anchor] = value if node.anchor
+      value
+    end
+  end
+end

data/app/models/paper_view/timeline.rb

@@ -0,0 +1,62 @@
+module PaperView
+  class Timeline
+    Group = Struct.new(:label, :rows)
+
+    attr_reader :rows
+
+    def initialize(versions, selected_id: nil)
+      bursts = burst_sizes(versions)
+      @rows = versions.map { |version| VersionRow.new(version, burst_size: bursts[version.id]) }
+      @selected_id = selected_id
+    end
+
+    def empty?
+      rows.empty?
+    end
+
+    def groups
+      rows.chunk_while { |one, other| one.date == other.date }
+        .map { |chunk| Group.new(day_label(chunk.first.date), chunk) }
+    end
+
+    def items
+      @items ||= rows.map(&:item_key).uniq
+    end
+
+    def stream?
+      items.size != 1
+    end
+
+    def title
+      stream? ? "All changes" : rows.first.item_label
+    end
+
+    def selected
+      @selected ||= rows.find { |row| row.id.to_s == @selected_id.to_s } || newest
+    end
+
+    private
+
+    def newest
+      rows.max_by { |row| [row.version.created_at || Time.at(0), row.id] }
+    end
+
+    def burst_sizes(versions)
+      versions.group_by { |version| [version.whodunnit, version.created_at&.to_i] }
+        .each_with_object({}) { |(_, group), sizes| group.each { |version| sizes[version.id] = group.size } }
+    end
+
+    def day_label(date)
+      return "Unknown date" if date.nil?
+
+      today = Date.current
+      full = date.strftime("%-d %B %Y")
+
+      case date
+      when today then "Today · #{full}"
+      when today - 1 then "Yesterday · #{full}"
+      else full
+      end
+    end
+  end
+end

data/app/models/paper_view/version_query.rb

@@ -0,0 +1,50 @@
+module PaperView
+  class VersionQuery
+    EVENTS = %w[create update destroy].freeze
+    FILTER_KEYS = %i[item_type item_id event].freeze
+    SORTS = %w[desc asc].freeze
+
+    attr_reader :item_type, :item_id, :event, :sort
+
+    def initialize(params = {})
+      @submitted = FILTER_KEYS.any? { |key| params.key?(key) }
+      @item_type = params[:item_type].presence
+      @item_id = params[:item_id].presence
+      @event = params[:event].presence_in(EVENTS)
+      @sort = params[:sort].presence_in(SORTS) || SORTS.first
+    end
+
+    def submitted?
+      @submitted
+    end
+
+    def item_types
+      @item_types ||= versions_table.item_types
+    end
+
+    def relation
+      scope = PaperView.version_class.all
+      scope = scope.where(item_type: searched_item_types) if searched_item_types
+      scope = scope.where(item_id: item_id) if item_id
+      scope = scope.where(event: event) if event
+      scope.order(created_at: sort.to_sym, id: sort.to_sym)
+    end
+
+    def label
+      return "All versions" unless item_type
+      item_id ? "#{item_type} ##{item_id}" : item_type
+    end
+
+    private
+
+    def versions_table
+      @versions_table ||= VersionsTable.new
+    end
+
+    def searched_item_types
+      return @searched_item_types if defined?(@searched_item_types)
+
+      @searched_item_types = item_type || (item_types if item_id && versions_table.item_type_indexed?)
+    end
+  end
+end