lethe 0.1.0

data/lib/lethe/formatters.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module Lethe
+  # Turn a Report into text for people, GitHub Actions annotations, or JSON.
+  module Formatters
+    MARKS = {covered: "✓", ignored: "✓", missing: "✗", guess: "?", invalid: "!"}.freeze
+
+    def self.for(name)
+      case name.to_s
+      when "", "text" then Text
+      when "github" then GitHub
+      when "json" then JSON
+      else raise ArgumentError, "lethe: unknown format #{name.inspect}; use text, github or json"
+      end
+    end
+
+    class Base
+      # root: paths in locations are shown relative to it.
+      # definition_path: where problems without a location point (the definitions file).
+      def initialize(report, root: Dir.pwd, locale: I18n.default_locale, definition_path: nil)
+        @report = report
+        @root = Pathname(root)
+        @locale = locale
+        @definition_path = definition_path
+      end
+
+      private
+
+      def t(key, **values)
+        I18n.t(key, **values, locale: @locale)
+      end
+
+      # The sentence for a result that needs one.
+      def message(result)
+        case result.status
+        when :missing
+          if result.key == "subject"
+            t("lethe.check.subject_missing", subject: result.subject)
+          else
+            t("lethe.check.missing", vias: vias(result.reference))
+          end
+        when :guess
+          t("lethe.check.guess", vias: vias(result.reference), subject: result.subject)
+        when :invalid
+          key, values = result.message
+          t("lethe.messages.#{key}", subject: result.subject, **values)
+        end
+      end
+
+      def vias(reference)
+        reference.vias.map { |via| t("lethe.vias.#{via}") }.join(t("lethe.export.list_separator"))
+      end
+
+      # [path, line] relative to root, or nil.
+      def location(result)
+        return nil unless result.location
+
+        path, line = result.location.match(/\A(.*):(\d+)\z/)&.captures
+        return nil unless path
+
+        [relative(path), line.to_i]
+      end
+
+      def relative(path)
+        Pathname(path).relative_path_from(@root).to_s
+      rescue ArgumentError
+        path
+      end
+    end
+
+    class Text < Base
+      def render
+        lines = []
+        @report.subjects.each do |subject|
+          results = @report.results.select { |result| result.subject == subject }
+          lines.concat(subject_lines(subject, results))
+          lines << ""
+        end
+        lines << totals
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def subject_lines(subject, results)
+        references = results.filter_map(&:reference)
+        counts = references.flat_map(&:vias).tally.sort_by { |via, _| via.to_s }
+        vias = counts.map { |via, count| "#{t("lethe.vias.#{via}")} #{count}" }.join(t("lethe.export.list_separator"))
+        lines = [t("lethe.check.summary", subject: subject, count: references.size, vias: vias), ""]
+
+        covered = results.count { |result| result.reference && (result.status == :covered || result.status == :ignored) }
+        lines << "#{MARKS[:covered]} #{t("lethe.check.covered", count: covered)}"
+
+        listed = results.reject { |result| result.status == :covered || result.status == :ignored }
+        width = listed.map { |result| label(result).length }.max || 0
+        listed.each do |result|
+          lines << "#{MARKS[result.status]} #{label(result).ljust(width)}  #{message(result)}"
+        end
+        lines
+      end
+
+      def label(result)
+        where = location(result)
+        prefix = where ? "#{where.join(":")} " : ""
+        "#{prefix}#{result.key}"
+      end
+
+      def totals
+        problems = @report.problems.size
+        guesses = @report.strict? ? 0 : @report.count(:guess)
+        return t("lethe.check.clean") if problems.zero? && guesses.zero?
+
+        t("lethe.check.totals", problems: problems, guesses: guesses)
+      end
+    end
+
+    # GitHub Actions workflow commands, one per problem or guess.
+    class GitHub < Base
+      def render
+        @report.results.filter_map { |result| annotation(result) }.join("\n").then { |text| text.empty? ? "" : "#{text}\n" }
+      end
+
+      private
+
+      def annotation(result)
+        level =
+          if result.problem?(strict: @report.strict?) then "error"
+          elsif result.status == :guess then "warning"
+          end
+        return nil unless level
+
+        path, line = location(result) || [@definition_path && relative(@definition_path), nil]
+        properties = {"file" => path, "line" => line, "title" => "lethe: #{result.subject} #{result.key}"}
+          .compact.map { |name, value| "#{name}=#{escape_property(value.to_s)}" }.join(",")
+        "::#{level} #{properties}::#{escape_data(message(result))}"
+      end
+
+      # https://docs.github.com/actions/reference/workflow-commands-for-github-actions
+      def escape_data(value)
+        value.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+
+      def escape_property(value)
+        escape_data(value).gsub(":", "%3A").gsub(",", "%2C")
+      end
+    end
+
+    class JSON < Base
+      def render
+        ::JSON.pretty_generate(
+          "version" => 1,
+          "clean" => @report.clean?,
+          "strict" => @report.strict?,
+          "results" => @report.results.map { |result| entry(result) }
+        ) + "\n"
+      end
+
+      private
+
+      def entry(result)
+        where = location(result)
+        {
+          "status" => result.status.to_s,
+          "subject" => result.subject,
+          "key" => result.key,
+          "vias" => result.reference&.vias&.map(&:to_s),
+          "actions" => result.policies.map { |policy| policy.action.to_s },
+          "file" => where&.first,
+          "line" => where&.last,
+          "message" => message(result)
+        }.compact
+      end
+    end
+  end
+end

data/lib/lethe/ledger.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lethe
+  # The lethe_erasures table: one row each time a subject is erased or its
+  # kept rows are swept, with the subject's class, id and the number of rows
+  # per table. Never anything personal. bin/rails generate lethe:install
+  # creates it.
+  module Ledger
+    TABLE = "lethe_erasures"
+
+    def self.available?(connection)
+      connection.data_source_exists?(TABLE)
+    end
+
+    def self.record(subject_type, subject_id, kind, counts)
+      Rows.for(TABLE).create!(
+        subject_type: subject_type, subject_id: subject_id.to_s, kind: kind,
+        counts: JSON.generate(counts), created_at: Time.current
+      )
+    end
+
+    # { subject_id => when it was first erased }
+    def self.erased(subject_type)
+      Rows.for(TABLE).where(subject_type: subject_type, kind: "erase").group(:subject_id).minimum(:created_at)
+    end
+  end
+end

data/lib/lethe/leftovers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Lethe
+  # After an erasure, finds what still points at the subject in a way the
+  # definition does not allow: rows that should be gone, columns that should
+  # have been overwritten, attachments, and the subject's own row.
+  #
+  # Kept rows are allowed. Values computed by a Proc cannot be compared, so
+  # those columns are not checked.
+  class Leftovers
+    Leftover = Data.define(:key, :problem, :count) do
+      def to_s
+        "#{key}: #{count} #{problem.to_s.tr("_", " ")}"
+      end
+    end
+
+    def initialize(subject, id, definition, results, models:)
+      @subject = subject
+      @id = id
+      @definition = definition
+      @results = results
+      @locator = Locator.new(subject, models: models)
+    end
+
+    def call
+      references + attachments + subject_row
+    end
+
+    private
+
+    def covered
+      @results.select { |result| result.status == :covered && result.reference }
+    end
+
+    def references
+      covered.reject { |result| result.reference.attachment }.flat_map do |result|
+        policies = result.policies.reject(&:ignore?)
+        next [] if policies.empty?
+
+        location = @locator.locate(policies.first)
+        base = @locator.rows(location).where(@locator.conditions(location, nil, @id)).where(declared_type(location, policies))
+        found = []
+
+        allowed = policies.select { |policy| %i[keep scrub].include?(policy.action) }
+        unless allowed.any? { |policy| policy.where.nil? }
+          staying = allowed.map { |policy| base.where(Enums.cast(location.model, policy.where)) }.reduce { |all, scope| all.or(scope) }
+          count = base.count - (staying ? staying.count : 0)
+          found << Leftover.new(key: result.key, problem: :not_deleted, count: count) if count.positive?
+        end
+
+        allowed.select { |policy| policy.action == :scrub }.each do |policy|
+          fixed = policy.set.reject { |_, value| value.is_a?(Proc) }
+          next if fixed.empty?
+
+          count = base.where(Enums.cast(location.model, policy.where || {})).where.not(Enums.cast(location.model, fixed)).count
+          found << Leftover.new(key: result.key, problem: :not_scrubbed, count: count) if count.positive?
+        end
+        found
+      end
+    end
+
+    # A "table.column" target names its polymorphic type in where:, which
+    # the checker requires; the rows of other types are not this subject's.
+    def declared_type(location, policies)
+      return {} if location.type_column
+
+      type_column = "#{location.column.delete_suffix("_id")}_type"
+      return {} unless @locator.rows(location).column_names.include?(type_column)
+
+      Enums.cast(location.model, policies.first.where).transform_keys(&:to_s).slice(type_column)
+    end
+
+    def attachments
+      return [] unless defined?(ActiveStorage::Attachment) && ActiveStorage::Attachment.table_exists?
+
+      covered.select { |result| result.reference.attachment }.filter_map do |result|
+        count = ActiveStorage::Attachment
+          .where(record_type: @subject.polymorphic_name, record_id: @id, name: result.reference.attachment).count
+        Leftover.new(key: result.key, problem: :attachment_remains, count: count) if count.positive?
+      end
+    end
+
+    def subject_row
+      policy = @definition.subject_policy
+      row = Rows.for(@subject.table_name).where(@subject.primary_key => @id)
+      return [] unless policy && row.exists?
+      return [Leftover.new(key: "subject", problem: :not_deleted, count: 1)] if policy.destroy
+
+      found = []
+      found << Leftover.new(key: "subject", problem: :not_marked_deleted, count: 1) if row.where(policy.soft_delete => nil).exists?
+      fixed = policy.scrub.reject { |_, value| value.is_a?(Proc) }
+      if fixed.any? && row.where.not(Enums.cast(@subject, fixed)).exists?
+        found << Leftover.new(key: "subject", problem: :not_scrubbed, count: 1)
+      end
+      found
+    end
+  end
+end

data/lib/lethe/locales/en.yml

@@ -0,0 +1,77 @@
+en:
+  lethe:
+    errors:
+      no_definitions_file: "lethe: %{path} not found. Declare your policies there, or set Lethe.configuration.definition_path."
+      load_failed: "lethe: could not load %{path}: %{error}"
+      ledger_required: "lethe: %{table} is missing; keep ..., for: needs it to know when a subject was erased. Run bin/rails generate lethe:install and migrate."
+      no_definition: "lethe: there is no Lethe.define for %{subject}"
+      foreign_key_cycle: "lethe: foreign keys between %{tables} form a cycle, so there is no order to delete them in; use cascade: true or remove one of the keys"
+    vias:
+      foreign_key: foreign key
+      association: association
+      join_table: join table
+      polymorphic: polymorphic association
+      polymorphic_guess: polymorphic belongs_to
+      attachment: attachment
+      column_name: column name
+      declared: declaration
+    check:
+      summary: "%{subject}: %{count} references (%{vias})"
+      covered: "%{count} have a policy"
+      missing: "no policy (found by %{vias})"
+      guess: "guessed from the %{vias}; declare a policy, or `ignore` it with a reason if it does not point at %{subject}"
+      subject_missing: "no `subject` declaration; say how the %{subject} row itself goes"
+      totals: "%{problems} problems, %{guesses} to confirm."
+      clean: "No problems."
+    messages:
+      subject_not_a_model: "%{subject} is not an Active Record model with a table"
+      no_association: "%{subject} has no association :%{name}"
+      through_association: ":%{name} goes through another association; declare the table it goes through instead"
+      association_class_missing: "the class of association :%{name} cannot be loaded"
+      belongs_to_association: ":%{name} is a belongs_to; it points away from %{subject}, not at it"
+      no_attachment: "%{subject} has no attachment :%{name}"
+      no_table: "there is no table %{table}"
+      no_column: "%{table} has no column %{column}"
+      reason_required: "%{action} needs a reason:"
+      reason_not_string: "reason: must be a String"
+      set_required: "scrub needs set: with the columns to overwrite"
+      where_not_hash: "where: must be a non-empty Hash of columns"
+      unknown_column: "%{option}: %{table} has no column %{column}"
+      unknown_enum_value: "%{option}: %{value} is not a value of the %{column} enum on %{table}"
+      retention_not_allowed: "for: belongs to keep and scrub, not %{action}"
+      cascade_without_retention: "cascade: on %{action} only applies when lethe:sweep deletes the rows; add for:, or leave cascade out"
+      retention_not_duration: "for: must be a duration such as 2.years"
+      contradiction: "%{key} already has a different policy at %{other}; limit one of them with where:"
+      polymorphic_type_required: "%{key} is polymorphic; add where: { %{type_column}: \"%{subject_type}\" } so other types' rows stay"
+      cascade_needs_model: "cascade: true needs a model for %{table}; without one, leave cascade out"
+      computed_set_needs_primary_key: "a Proc in set: needs %{table} to have a primary key, to update one row at a time"
+      kept_rows_block_destroy: "%{key} has a foreign key to %{subject}, so its rows cannot stay when subject destroy: true deletes the row; soft delete it instead"
+      subject_both: "subject cannot both destroy: and soft_delete:"
+      subject_neither: "subject needs destroy: true or soft_delete: :column"
+      subject_scrub_not_hash: "subject scrub: must be a Hash of columns"
+    export:
+      title: "What happens when a %{subject} leaves"
+      generated: "Generated by lethe from %{path}. Do not edit by hand; run bin/rails lethe:export."
+      data: Data
+      action: When they leave
+      retention: Kept for
+      reason: Reason
+      subject_row: "The %{subject} itself"
+      attachment: "%{name} (attachment)"
+      column_suffix: "%{label} (%{column})"
+      destroy: Deleted
+      destroy_attachment: Deleted
+      scrub: "Kept, with %{columns} overwritten"
+      keep: Kept
+      soft_delete: "Kept as deleted (%{column})"
+      soft_delete_scrub: "Kept as deleted (%{column}), with %{columns} overwritten"
+      where: "%{action}, where %{conditions}"
+      list_separator: ", "
+      parts:
+        years: "%{count} years"
+        months: "%{count} months"
+        weeks: "%{count} weeks"
+        days: "%{count} days"
+        hours: "%{count} hours"
+        minutes: "%{count} minutes"
+        seconds: "%{count} seconds"

data/lib/lethe/locales/ja.yml

@@ -0,0 +1,77 @@
+ja:
+  lethe:
+    errors:
+      no_definitions_file: "lethe: %{path} がありません。方針をそこに書くか、Lethe.configuration.definition_path を設定してください。"
+      load_failed: "lethe: %{path} を読み込めませんでした: %{error}"
+      ledger_required: "lethe: %{table} がありません。keep ..., for: には、いつ退会したかの記録が必要です。bin/rails generate lethe:install を実行して migrate してください。"
+      no_definition: "lethe: %{subject} の Lethe.define がありません"
+      foreign_key_cycle: "lethe: %{tables} の外部キーが循環していて、消す順番を決められません。cascade: true を使うか、外部キーを 1 つ外してください"
+    vias:
+      foreign_key: 外部キー
+      association: 関連
+      join_table: 中間テーブル
+      polymorphic: ポリモーフィック関連
+      polymorphic_guess: ポリモーフィックの belongs_to
+      attachment: 添付
+      column_name: 列名
+      declared: 宣言
+    check:
+      summary: "%{subject}: 参照 %{count} 件（%{vias}）"
+      covered: "%{count} 件に方針があります"
+      missing: "方針がありません（%{vias}で見つけました）"
+      guess: "%{vias}から推測しました。%{subject} を指すなら方針を、指さないなら理由をつけて ignore を書いてください"
+      subject_missing: "subject の宣言がありません。%{subject} の行そのものをどうするかを書いてください"
+      totals: "問題 %{problems} 件、要確認 %{guesses} 件。"
+      clean: "問題はありません。"
+    messages:
+      subject_not_a_model: "%{subject} はテーブルのある Active Record のモデルではありません"
+      no_association: "%{subject} に :%{name} という関連はありません"
+      through_association: ":%{name} は別の関連を通っています。通っている先のテーブルを宣言してください"
+      association_class_missing: ":%{name} のクラスを読み込めません"
+      belongs_to_association: ":%{name} は belongs_to です。%{subject} を指すのではなく、%{subject} から外を指しています"
+      no_attachment: "%{subject} に :%{name} という添付はありません"
+      no_table: "%{table} というテーブルはありません"
+      no_column: "%{table} に %{column} という列はありません"
+      reason_required: "%{action} には reason: が必要です"
+      reason_not_string: "reason: は文字列にしてください"
+      set_required: "scrub には、書き換える列を set: で書いてください"
+      where_not_hash: "where: は列と値の Hash にしてください"
+      unknown_column: "%{option}: %{table} に %{column} という列はありません"
+      unknown_enum_value: "%{option}: %{value} は %{table} の %{column} の enum にない値です"
+      retention_not_allowed: "for: は keep と scrub に書くものです（%{action} には書けません）"
+      cascade_without_retention: "%{action} の cascade: は lethe:sweep で消すときだけ効きます。for: を足すか、cascade を外してください"
+      retention_not_duration: "for: は 2.years のような期間にしてください"
+      contradiction: "%{key} には %{other} で別の方針があります。どちらかを where: で絞ってください"
+      polymorphic_type_required: "%{key} はポリモーフィックです。他の型の行を消さないよう where: { %{type_column}: \"%{subject_type}\" } を足してください"
+      cascade_needs_model: "cascade: true には %{table} のモデルが必要です。モデルがなければ cascade を外してください"
+      computed_set_needs_primary_key: "set: に Proc を書くには、1 行ずつ書き換えるため %{table} に主キーが必要です"
+      kept_rows_block_destroy: "%{key} は %{subject} への外部キーを持つため、subject destroy: true で行を消すと残せません。論理削除にしてください"
+      subject_both: "subject に destroy: と soft_delete: の両方は書けません"
+      subject_neither: "subject には destroy: true か soft_delete: :列名 が必要です"
+      subject_scrub_not_hash: "subject の scrub: は列と値の Hash にしてください"
+    export:
+      title: "%{subject} が退会するとどうなるか"
+      generated: "lethe が %{path} から書き出しました。手で直さず、bin/rails lethe:export を実行してください。"
+      data: データ
+      action: 退会すると
+      retention: 保存期間
+      reason: 理由
+      subject_row: "%{subject} 本体"
+      attachment: "%{name}（添付）"
+      column_suffix: "%{label}（%{column}）"
+      destroy: 消す
+      destroy_attachment: 消す
+      scrub: "残す。%{columns} は書き換える"
+      keep: 残す
+      soft_delete: "削除済みとして残す（%{column}）"
+      soft_delete_scrub: "削除済みとして残す（%{column}）。%{columns} は書き換える"
+      where: "%{conditions} のとき: %{action}"
+      list_separator: "、"
+      parts:
+        years: "%{count} 年"
+        months: "%{count} か月"
+        weeks: "%{count} 週間"
+        days: "%{count} 日"
+        hours: "%{count} 時間"
+        minutes: "%{count} 分"
+        seconds: "%{count} 秒"

data/lib/lethe/locator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Lethe
+  # Finds the rows a policy applies to, for one subject: the table, the
+  # column holding the subject's id, the polymorphic type column when there
+  # is one, and the application's model when cascade needs it.
+  class Locator
+    Location = Data.define(:table, :column, :type_column, :model)
+
+    def initialize(subject, models:)
+      @subject = subject
+      @models = models
+    end
+
+    def locate(policy)
+      target = policy.target
+      case target.kind
+      when :association then locate_association(target.name)
+      when :column then Location.new(table: target.table, column: target.column, type_column: nil, model: model_for(target.table))
+      else raise ArgumentError, "lethe: attachments have no table to locate"
+      end
+    end
+
+    # Conditions for the rows of one subject id (or several), with the
+    # polymorphic type and the policy's own where:.
+    def conditions(location, policy, id)
+      conditions = {location.column => id}
+      conditions[location.type_column] = @subject.polymorphic_name if location.type_column
+      conditions.merge(Enums.cast(location.model, policy&.where || {}).transform_keys(&:to_s))
+    end
+
+    def rows(location)
+      Rows.for(location.table)
+    end
+
+    private
+
+    def locate_association(name)
+      reflection = @subject.reflect_on_association(name)
+      if reflection.options[:primary_key]
+        raise Error, "lethe: :#{name} uses primary_key:, which lethe does not support yet"
+      end
+
+      if reflection.macro == :has_and_belongs_to_many
+        Location.new(table: reflection.join_table.to_s, column: reflection.foreign_key.to_s, type_column: nil, model: nil)
+      else
+        type_column = reflection.options[:as] ? reflection.type.to_s : nil
+        Location.new(
+          table: reflection.klass.table_name, column: reflection.foreign_key.to_s,
+          type_column: type_column, model: reflection.klass
+        )
+      end
+    end
+
+    def model_for(table)
+      @models.find { |model| model.table_name == table && model.base_class == model }
+    end
+  end
+end

data/lib/lethe/plan.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Lethe
+  # What erasing one subject record will do, step by step, with the number
+  # of rows each step touches. Building a plan changes nothing.
+  #
+  # Steps run in this order: attachments, deletions (rows that point at
+  # other deleted tables first), overwrites, kept rows (nothing happens to
+  # them), and the subject's own row last.
+  class Plan
+    include Enumerable
+
+    Step = Data.define(:kind, :key, :policy, :location, :conditions, :count) do
+      def to_s
+        what =
+          case kind
+          when :destroy then policy.cascade ? "destroy (cascade)" : "destroy"
+          when :scrub then "scrub #{policy.set.keys.join(", ")}"
+          when :keep then policy.retention ? "keep for #{policy.retention.inspect}" : "keep"
+          when :attachment then "purge"
+          else kind.to_s
+          end
+        "#{what.ljust(20)} #{key.ljust(36)} #{count} #{(count == 1) ? "row" : "rows"}"
+      end
+    end
+
+    attr_reader :record, :definition, :steps
+
+    def initialize(record, definition, results, models:, connection:)
+      @record = record
+      @definition = definition
+      @connection = connection
+      @locator = Locator.new(record.class, models: models)
+      @steps = build(results)
+    end
+
+    def each(&)
+      steps.each(&)
+    end
+
+    def to_s
+      steps.join("\n")
+    end
+
+    attr_reader :locator
+
+    private
+
+    def build(results)
+      covered = results.select { |result| result.status == :covered && result.subject == @definition.subject_name }
+      steps = covered.flat_map do |result|
+        result.policies.reject(&:ignore?).map { |policy| step_for(result.key, policy) }
+      end
+      attachments, rest = steps.partition { |step| step.kind == :attachment }
+      destroys = rest.select { |step| step.kind == :destroy }
+      others = rest - destroys
+      attachments + order_destroys(destroys) + others.sort_by { |step| [(step.kind == :scrub) ? 0 : 1, step.key] } + [subject_step]
+    end
+
+    def step_for(key, policy)
+      if policy.action == :destroy_attachment
+        return Step.new(kind: :attachment, key: key, policy: policy, location: nil, conditions: nil, count: attachment_count(policy.target.name))
+      end
+
+      location = @locator.locate(policy)
+      conditions = @locator.conditions(location, policy, @record.id)
+      Step.new(
+        kind: policy.action, key: key, policy: policy, location: location,
+        conditions: conditions, count: @locator.rows(location).where(conditions).count
+      )
+    end
+
+    def attachment_count(name)
+      attached = @record.public_send(name)
+      if attached.respond_to?(:attachments)
+        attached.attachments.size
+      else
+        (attached.attached? ? 1 : 0)
+      end
+    end
+
+    def subject_step
+      table = @record.class.table_name
+      location = Locator::Location.new(table: table, column: @record.class.primary_key, type_column: nil, model: nil)
+      conditions = {location.column => @record.id}
+      count = Rows.for(table).where(conditions).count
+      Step.new(kind: :subject, key: "subject", policy: @definition.subject_policy, location: location, conditions: conditions, count: count)
+    end
+
+    # Rows in a table with a foreign key to another table being deleted go first.
+    def order_destroys(destroys)
+      tables = destroys.map { |step| step.location.table }.uniq
+      before = tables.to_h do |table|
+        referenced = @connection.foreign_keys(table).map(&:to_table) & tables
+        [table, referenced - [table]]
+      end
+
+      ordered = []
+      remaining = tables.sort
+      until remaining.empty?
+        ready = remaining.select { |table| remaining.none? { |other| before[other].include?(table) } }
+        raise Error, I18n.t("lethe.errors.foreign_key_cycle", tables: remaining.join(", ")) if ready.empty?
+
+        ordered.concat(ready)
+        remaining -= ready
+      end
+      destroys.sort_by { |step| [ordered.index(step.location.table), step.key] }
+    end
+  end
+end

data/lib/lethe/policy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lethe
+  # One declared policy for one target.
+  #
+  #   action    :destroy, :scrub, :keep, :ignore or :destroy_attachment
+  #   reason    why, in words for people (required for keep and ignore)
+  #   retention how long a kept or scrubbed row stays (an ActiveSupport::Duration), or nil
+  #   where     a hash of column conditions the policy is limited to, or nil
+  #   set       for scrub: the columns to overwrite and their new values;
+  #             a Proc is called for each row (with the row, if it takes one)
+  #   cascade   delete through Active Record, so that dependent: associations,
+  #             callbacks and attachments go too: when erasing, for destroy;
+  #             when sweeping, for keep and scrub with a retention
+  #   location  "path:line" of the declaration
+  Policy = Data.define(:action, :target, :reason, :retention, :where, :set, :cascade, :location) do
+    def ignore?
+      action == :ignore
+    end
+
+    def computed_set?
+      set.is_a?(Hash) && set.values.any?(Proc)
+    end
+  end
+
+  # How the subject's own row goes away.
+  SubjectPolicy = Data.define(:destroy, :soft_delete, :scrub, :location)
+
+  # A block to run inside the erasure's transaction: :before or :after.
+  Hook = Data.define(:moment, :block, :location)
+end

data/lib/lethe/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Lethe
+  # Adds the rake tasks, and nothing else: lethe does not run inside the application.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/lethe.rake", __dir__)
+    end
+  end
+end