moderate 0.1.0 → 1.0.0.beta1

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,36 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 7.2.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "activejob"
+  gem "actionmailer"
+  gem "activestorage"
+  gem "sqlite3"
+  gem "pg"
+  gem "mysql2"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,36 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rake", "~> 13.0"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "appraisal"
+  gem "web-console"
+  gem "standard"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-minitest", "~> 0.35"
+  gem "rubocop-performance", "~> 1.0"
+end
+
+group :test do
+  gem "minitest", "~> 5.0"
+  gem "mocha"
+  gem "simplecov", require: false
+  gem "activejob"
+  gem "actionmailer"
+  gem "activestorage"
+  gem "sqlite3"
+  gem "pg"
+  gem "mysql2"
+  gem "bootsnap", require: false
+  gem "puma"
+  gem "importmap-rails"
+  gem "sprockets-rails"
+  gem "stimulus-rails"
+  gem "turbo-rails"
+  gem "rdoc", ">= 7.0"
+end
+
+gemspec path: "../"

data/lib/generators/moderate/install_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Moderate
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Install moderate migrations and initializer"
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_moderate_tables.rb.erb", File.join(db_migrate_path, "create_moderate_tables.rb")
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/moderate.rb"
+      end
+
+      def display_post_install_message
+        say "\n🛡️  The `moderate` gem has been installed.", :green
+        say "\nTo complete the setup:"
+
+        say "  1. Run 'rails db:migrate' to create the moderation tables."
+        say "     ⚠️  You must run migrations before starting your app!", :yellow
+
+        say "  2. Tell `moderate` who your users are in config/initializers/moderate.rb:"
+        say "       config.user_class = \"User\""
+
+        say "  3. Add the mixins to your models:"
+        say "       class User < ApplicationRecord"
+        say "         include Moderate::Actor       # can report, block, and be blocked"
+        say "       end"
+        say ""
+        say "       class Message < ApplicationRecord"
+        say "         include Moderate::Reportable  # can be reported"
+        say "         moderates :body               # and filtered before save"
+        say "       end"
+
+        say "\nYou now have reporting, blocking, filtering, and a moderation queue. 🚀\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/moderate/templates/create_moderate_tables.rb.erb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+class CreateModerateTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    # ---------------------------------------------------------------------------
+    # moderate_reports
+    #
+    # A report/notice + an immutable evidence snapshot + decision metadata + the
+    # appeal window. Serves both in-app community reports and public DSA legal
+    # notices (distinguished by `intake_kind`).
+    # ---------------------------------------------------------------------------
+    create_table :moderate_reports, id: primary_key_type do |t|
+      # Who reported (a user), and who they reported (a user). Nullable because
+      # DSA public notices can come from non-users, and reported content does not
+      # always resolve to a single account.
+      t.references :reporter, type: foreign_key_type, null: true
+      t.references :reported_user, type: foreign_key_type, null: true
+
+      # The reported content (any Moderate::Reportable model), polymorphic.
+      # `index: false` because we declare the polymorphic index explicitly below
+      # (`index_moderate_reports_on_reportable`); without this, `t.references` would
+      # ALSO auto-create an index on [reportable_type, reportable_id], and the two
+      # collide ("index ... already exists") when the migration runs. Suppressing the
+      # auto-index leaves exactly the one named index this schema intends.
+      t.references :reportable, polymorphic: true, type: foreign_key_type, null: true, index: false
+
+      # Which field of the reportable was reported (e.g. "description").
+      t.string :reported_field
+
+      # In-app community category vs. DSA legal taxonomy.
+      t.string :intake_kind, null: false, default: "community"
+      t.string :category, null: false
+      t.string :content_type
+      t.string :legal_reason
+      t.string :legal_country_code
+
+      # The reporter's substantiated reason.
+      t.text :message, null: false
+      t.boolean :anonymous, null: false, default: false
+      t.boolean :good_faith_confirmed, null: false, default: false
+
+      # DSA public-notice notifier identity (when not an authenticated user).
+      t.string :notifier_name
+      t.string :notifier_email
+      t.string :reported_account_identifier
+      t.string :subject_url
+      t.send(json_column_type, :subject_urls, null: false, default: json_array_default)
+
+      # Immutable evidence snapshot + automated-processing metadata.
+      t.send(json_column_type, :snapshot, null: false, default: json_column_default)
+      t.send(json_column_type, :automated_processing, null: false, default: json_column_default)
+
+      # Lifecycle + decision.
+      t.string :status, null: false, default: "open"
+      t.datetime :acknowledged_at
+      t.references :resolved_by, type: foreign_key_type, null: true
+      t.datetime :resolved_at
+      t.string :resolution_basis
+      t.text :resolution_note
+      t.send(json_column_type, :resolution_actions, null: false, default: json_column_default)
+
+      # Statement-of-reasons / appeal window (DSA Art. 17 & 20).
+      t.string :decision_visibility
+      t.datetime :decision_notified_at
+      t.datetime :affected_user_notified_at
+      t.datetime :appeal_deadline_at
+
+      t.timestamps
+    end
+
+    add_index :moderate_reports, [:reportable_type, :reportable_id], name: "index_moderate_reports_on_reportable"
+    add_index :moderate_reports, [:reported_user_id, :status], name: "index_moderate_reports_on_reported_user_id_and_status"
+    add_index :moderate_reports, [:reporter_id, :created_at], name: "index_moderate_reports_on_reporter_id_and_created_at"
+    add_index :moderate_reports, [:status, :created_at], name: "index_moderate_reports_on_status_and_created_at"
+    add_index :moderate_reports, [:intake_kind, :created_at], name: "index_moderate_reports_on_intake_kind_and_created_at"
+    add_index :moderate_reports, [:legal_reason, :created_at], name: "index_moderate_reports_on_legal_reason_and_created_at"
+    add_index :moderate_reports, :notifier_email, name: "index_moderate_reports_on_notifier_email"
+    add_index :moderate_reports, :resolved_at, name: "index_moderate_reports_on_resolved_at"
+    add_index :moderate_reports, :appeal_deadline_at, name: "index_moderate_reports_on_appeal_deadline_at"
+
+    # NOTE: the value-list taxonomies (category, intake_kind, status, content_type,
+    # legal_reason, legal_country_code, resolution_basis) are validated in the MODELS
+    # (frozen constants + ActiveModel inclusion validations), NOT by DB check
+    # constraints. That's deliberate: a host must be able to add a community
+    # `category` (Report.report_categories via config.report_categories) or have the
+    # gem grow its taxonomy WITHOUT shipping a migration to widen a CHECK. So the only
+    # constraints here are STRUCTURAL — NOT NULLs (above), FKs, the unique block edge,
+    # the self-block CHECK, and this cheap message-length guardrail (a runaway free-text
+    # field is a DB-level concern worth keeping even though the model also caps it).
+    add_check_constraint :moderate_reports,
+      "#{char_length_fn}(message) <= 4000",
+      name: "moderate_reports_message_length_check"
+
+    # ---------------------------------------------------------------------------
+    # moderate_blocks
+    #
+    # The bidirectional blocker/blocked edge, with a self-block check. This is the
+    # single source of truth behind Moderate.blocked_ids_for.
+    # ---------------------------------------------------------------------------
+    create_table :moderate_blocks, id: primary_key_type do |t|
+      t.references :blocker, type: foreign_key_type, null: false
+      t.references :blocked, type: foreign_key_type, null: false, index: { name: "index_moderate_blocks_on_blocked_id" }
+
+      t.timestamps
+    end
+
+    add_index :moderate_blocks, [:blocker_id, :blocked_id], unique: true, name: "index_moderate_blocks_on_blocker_id_and_blocked_id"
+    add_index :moderate_blocks, :created_at, name: "index_moderate_blocks_on_created_at"
+
+    add_check_constraint :moderate_blocks,
+      "blocker_id <> blocked_id",
+      name: "moderate_blocks_no_self_block"
+
+    # ---------------------------------------------------------------------------
+    # moderate_flags
+    #
+    # System/auto-filter flags (source: text_filter / image_filter /
+    # external_classifier / manual). The queue both human admins and ML consumers
+    # read via `pending`.
+    # ---------------------------------------------------------------------------
+    create_table :moderate_flags, id: primary_key_type do |t|
+      # The flagged content (any Moderate::Reportable model), polymorphic.
+      t.references :flaggable, polymorphic: true, type: foreign_key_type, null: false
+      t.string :field, null: false
+
+      # Who owns the flagged content (a user), inferred from the flaggable.
+      t.references :owner, type: foreign_key_type, null: true
+
+      # Where the flag came from, and what it would do (:flag allows, :block rejects).
+      t.string :source, null: false
+      t.string :mode, null: false, default: "flag"
+
+      # Classifier output.
+      t.send(json_column_type, :categories, null: false, default: json_array_default)
+      t.send(json_column_type, :scores, null: false, default: json_column_default)
+      t.send(json_column_type, :context, null: false, default: json_column_default)
+      t.text :excerpt
+
+      # Lifecycle + decision.
+      t.string :status, null: false, default: "pending"
+      t.references :reviewed_by, type: foreign_key_type, null: true
+      t.datetime :reviewed_at
+      t.text :resolution_note
+
+      t.timestamps
+    end
+
+    add_index :moderate_flags, [:flaggable_type, :flaggable_id, :field], name: "index_moderate_flags_on_target_and_field"
+    add_index :moderate_flags, [:owner_id, :status], name: "index_moderate_flags_on_owner_id_and_status"
+    add_index :moderate_flags, [:status, :created_at], name: "index_moderate_flags_on_status_and_created_at"
+
+    # Flag's mode/source/status vocabularies are validated in Moderate::Flag
+    # (constants + inclusion validations), not by DB CHECK constraints — same
+    # migration-free-taxonomy rationale as moderate_reports above.
+
+    # ---------------------------------------------------------------------------
+    # moderate_appeals
+    #
+    # DSA Art. 20 internal complaints against a decision. Free, electronic, open
+    # for at least 6 months, and decided by a human.
+    # ---------------------------------------------------------------------------
+    create_table :moderate_appeals, id: primary_key_type do |t|
+      t.references :report, type: foreign_key_type, null: false, foreign_key: { to_table: :moderate_reports }
+
+      # Who appealed: a user, or a named/emailed notifier for public notices.
+      t.references :appellant, type: foreign_key_type, null: true
+      t.string :appellant_name
+      t.string :appellant_email
+      t.string :source, null: false, default: "notifier"
+
+      t.text :reason, null: false
+      t.send(json_column_type, :snapshot, null: false, default: json_column_default)
+
+      # Lifecycle + decision.
+      t.string :status, null: false, default: "open"
+      t.references :resolved_by, type: foreign_key_type, null: true
+      t.datetime :resolved_at
+      t.text :resolution_note
+      t.datetime :decision_notified_at
+
+      t.timestamps
+    end
+
+    add_index :moderate_appeals, [:report_id, :created_at], name: "index_moderate_appeals_on_report_id_and_created_at"
+    add_index :moderate_appeals, [:status, :created_at], name: "index_moderate_appeals_on_status_and_created_at"
+    add_index :moderate_appeals, :appellant_email, name: "index_moderate_appeals_on_appellant_email"
+
+    # Appeal's source/status vocabularies are validated in Moderate::Appeal
+    # (constants + inclusion validations), not by DB CHECK constraints — same
+    # migration-free-taxonomy rationale as moderate_reports above.
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns.
+  # Returns an empty-hash default for SQLite/PostgreSQL, nil for MySQL.
+  # Models handle nil metadata gracefully by defaulting to {} in their accessors.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.include?("mysql")
+
+    {}
+  end
+
+  # Same MySQL caveat as `json_column_default`, but for list-shaped columns,
+  # which default to an empty array on SQLite/PostgreSQL.
+  def json_array_default
+    return nil if connection.adapter_name.downcase.include?("mysql")
+
+    []
+  end
+
+  # The SQL function for COUNTING CHARACTERS in a check constraint, chosen per
+  # adapter so the message-length guard is portable:
+  #   - SQLite has no `char_length`; its `length(text)` already counts CHARACTERS.
+  #   - PostgreSQL & MySQL 8+ both provide `char_length` (true character count,
+  #     unlike MySQL's `length`, which counts BYTES). Using `char_length` there
+  #     makes the 4000 cap a real character cap on every adapter, not a byte cap.
+  def char_length_fn
+    connection.adapter_name.downcase.include?("sqlite") ? "length" : "char_length"
+  end
+end

data/lib/generators/moderate/templates/initializer.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+Moderate.configure do |config|
+  # ==========================================================================
+  # WHO ARE YOUR USERS?
+  # ==========================================================================
+  #
+  # The model that reports, blocks, gets reported, and gets banned. This is the
+  # model where you `include Moderate::Actor`. Stored as a string and resolved
+  # lazily, so it works no matter when your app boots.
+  #
+  # Default: "User"
+  config.user_class = "User"
+
+  # ==========================================================================
+  # CONTENT FILTERING
+  # ==========================================================================
+  #
+  # The default mode used by `moderates :field` when you don't pass `mode:`.
+  #
+  #   :off    - no check (filtering disabled for fields that don't override it)
+  #   :block  - reject the save with a validation error if the filter trips
+  #   :flag   - let the save through, then create a Moderate::Flag after commit
+  #             for human or automated review (great for DMs, where you never
+  #             want to block someone mid-conversation)
+  #
+  # Default: :block
+  # config.default_filter_mode = :block
+
+  # The default text adapter used by `moderates :field` and `Moderate.classify`.
+  # Every adapter implements the same tiny contract — `classify(value) → Result`
+  # — so they're interchangeable per field. `moderate` ships exactly ONE built-in
+  # adapter; anything else (text-with-context, images, a hosted moderation API) is
+  # bring-your-own (`register_adapter`, below):
+  #
+  #   :wordlist - fast, multilingual, offline wordlist (ships en/es). The ONLY
+  #               built-in. Fast offline baseline; register a remote/contextual
+  #               adapter when you need stronger checks.
+  #
+  # Default: :wordlist
+  # config.filter_adapter = :wordlist
+
+  # Per-field filter policies, declared in one place instead of (or in addition
+  # to) `moderates :field` in your models. Handy when you want all your T&S
+  # configuration to live in this initializer.
+  #
+  # Signature: filter <ClassName>, <field>, with: <adapter>, mode: <mode>
+  #
+  # config.filter "Message", :body,   with: :wordlist, mode: :flag
+  # config.filter "Profile", :bio,    with: :wordlist, mode: :block
+  # config.filter "Profile", :avatar, with: :rekognition, mode: :flag  # a registered adapter (see below)
+
+  # Bring your own adapter — it's just an object that responds to `classify`,
+  # returning a Moderate::Result. Register it once, then reference it by name
+  # in `moderates` or `config.filter` with `with: :my_adapter`.
+  #
+  # Two ready-to-copy reference adapters ship under the gem's examples/ directory —
+  # OpenAI moderation (text + image, via the ruby_llm gem) and AWS Rekognition
+  # (images). They are NOT a dependency: copy one into your app, add its gem to your
+  # Gemfile, and register it here. Async adapters (a remote classifier) are only valid
+  # in :flag mode; :block needs the synchronous :wordlist.
+  #
+  # config.register_adapter :openai, OpenAIModerationAdapter.new
+  # config.register_adapter :my_adapter, MyAdapter.new
+
+  # Extra wordlist entries layered on top of the built-in lists, and entries to
+  # exclude (false positives you never want flagged in your domain). Both apply
+  # to the :wordlist adapter.
+  #
+  # config.additional_words = %w[customword anotherword]
+  # config.excluded_words   = %w[scunthorpe assangea]
+
+  # Override the in-app COMMUNITY report category list (what a user picks from a
+  # "Report" sheet). Defaults to Moderate::Report::DEFAULT_CATEGORIES. Adding a
+  # category here requires NO migration — `category` is validated in the model. (The
+  # separate, regulator-defined DSA legal-reason taxonomy is NOT overridable.)
+  #
+  # config.report_categories = %w[harassment hate spam fraud my_custom_label]
+
+  # ==========================================================================
+  # AUDIT — one hook, recorded however you want
+  # ==========================================================================
+  #
+  # Called for every important action so you can write it to YOUR audit system.
+  # `moderate` never writes to your audit log directly — it just emits the event.
+  # No-op by default.
+  #
+  # The event carries a stable envelope:
+  #   event.name        # Symbol, e.g. :report_decision
+  #   event.subject      # the record acted on (a Report, Block, Flag, Appeal…)
+  #   event.actor        # who took the action (a moderator, a user, or nil/system)
+  #   event.recipients   # who should be notified (Array)
+  #   event.payload      # Hash of event-specific context (includes :summary)
+  #   event.to_h         # the whole envelope as a Hash
+  #
+  # config.audit = ->(event) { AuditLog.record!(event_type: event.name, data: event.payload) }
+
+  # ==========================================================================
+  # NOTIFY — one hook, fan out anywhere
+  # ==========================================================================
+  #
+  # Called for every notifiable event. Wire it once and fan out to email
+  # (goodmail), admin alerts (telegrama), in-app + push (noticed) — all from the
+  # same place. No-op by default.
+  #
+  # The full event vocabulary:
+  #   :report_received        :report_decision        :affected_user_decision
+  #   :appeal_received        :appeal_decision
+  #   :user_blocked           :user_unblocked         :user_banned
+  #   :content_flagged        :content_removed
+  #
+  # IMPORTANT: keep this fast. Use background jobs (deliver_later, perform_later)
+  # so notifications never block a moderation action.
+  #
+  # config.notify = ->(event) do
+  #   case event.name
+  #   when :report_received, :report_decision, :affected_user_decision
+  #     # email the user — goodmail
+  #     ModerationMailer.with(event: event).public_send(event.name).deliver_later
+  #   when :content_flagged
+  #     # ping admins — telegrama
+  #     Telegrama.send_message("🚩 #{event.payload[:summary]}")
+  #   end
+  # end
+
+  # ==========================================================================
+  # ON BLOCK — optional side effects when one user blocks another
+  # ==========================================================================
+  #
+  # Run extra teardown when a block happens (cancel a pending invite, leave a
+  # shared room, drop a follow…). No-op by default. Signature uses keyword args.
+  #
+  # config.on_block = ->(blocker:, blocked:, at:) { CancelPendingInvites.call(blocker, blocked, at: at) }
+
+  # ==========================================================================
+  # BAN HANDLER — how a "ban" is actually applied in YOUR app
+  # ==========================================================================
+  #
+  # `moderate` doesn't own your user lifecycle, so it never bans a user itself.
+  # When a moderator resolves a report with `ban_user: true`, this proc decides
+  # what "banned" means in your domain — suspend, soft-delete, flip a flag, etc.
+  # Signature uses keyword args. No-op by default (the action still audits).
+  #
+  # config.ban_handler = ->(user:, by:, reason:) { user.suspend!(reason: reason) }
+
+  # ==========================================================================
+  # PUBLIC FORM HUMAN VERIFICATION — optional per-request skips
+  # ==========================================================================
+  #
+  # The notice and appeal forms auto-use rails_cloudflare_turnstile when present,
+  # otherwise they fall back to notice_guard / appeal_guard. If one of your clients
+  # cannot render a browser challenge (for example a native shell or an edge-verified
+  # request), skip the human-verification gate for that request only. Nil by default.
+  #
+  # config.notice_human_verification_skip_if = ->(controller) {
+  #   controller.request.user_agent.to_s.match?(/Hotwire Native/i)
+  # }
+  #
+  # config.appeal_human_verification_skip_if = ->(controller) {
+  #   controller.request.user_agent.to_s.match?(/Hotwire Native/i)
+  # }
+
+  # ==========================================================================
+  # PUBLIC TRANSPARENCY REPORT (DSA Art. 24) — opt-in
+  # ==========================================================================
+  #
+  # OFF by default. A *live* transparency portal is not itself a legal requirement:
+  # the DSA obligation is to *publish* a report at least annually (a static page/file
+  # is fine), and micro/small enterprises are exempt from the transparency tier
+  # entirely (Art. 15(2) / Art. 19). Turn it on to expose the mounted
+  # `<mount>/transparency` page; left off, that route 404s and the counts are never
+  # published. The aggregation is still queryable in code so you can build your own.
+  #
+  # config.transparency_report_enabled = true
+
+  # ==========================================================================
+  # SIGNED LINKS — purposes for the signed Global IDs in emails & notices
+  # ==========================================================================
+  #
+  # `moderate` mints signed, single-purpose links (e.g. an appeal link in a
+  # decision email, a confirm-receipt link in a DSA notice). These purposes
+  # scope each signature so a link minted for one action can't be replayed for
+  # another. The defaults cover the built-in flows; add your own if you mint
+  # custom signed links against moderate records.
+  #
+  # Default: [:appeal, :confirm_notice, :unsubscribe]
+  # config.signed_gid_purposes = [:appeal, :confirm_notice, :unsubscribe]
+
+  # ==========================================================================
+  # LOCALE
+  # ==========================================================================
+  #
+  # The locale used for user-facing copy moderate generates on its own (filter
+  # validation messages, the DSA statement-of-reasons taxonomy labels, the
+  # notice-form strings). Defaults to your app's I18n.default_locale.
+  #
+  # config.locale = :en
+end

data/lib/generators/moderate/views_generator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Moderate
+  module Generators
+    # `rails generate moderate:views` — eject the engine's overridable templates
+    # into the HOST app so they can be restyled. This is the Devise move
+    # (`rails g devise:views`), and it works for the same boring Rails reason:
+    # the host app's `app/views` sits AHEAD of any engine's view paths in the
+    # lookup chain, so a file copied to `app/views/moderate/notices/new.html.erb`
+    # SHADOWS the gem's bundled default automatically — no config, no registration.
+    # Delete your copy and the gem's default comes back. Upgrade the gem and your
+    # ejected copies are untouched (re-run only if you WANT the new defaults).
+    #
+    # `source_root` points at the engine's own `app/views`, so `copy_file` /
+    # `directory` read the exact templates the engine renders.
+    class ViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../app/views", __dir__)
+
+      desc "Copy moderate's overridable notice-form views into your app so you can restyle them."
+
+      # Which groups to eject. Default copies the notice views and the engine layout
+      # (the full set). `--views form` copies just the field partial — the part a
+      # host most often wants to restyle — and `--views form layout` adds the layout.
+      class_option :views,
+        type: :array,
+        default: %w[notices layout],
+        desc: "Which view groups to copy (notices, form, layout)"
+
+      def copy_views
+        # The whole notices directory (new/show + any partials that ship with it).
+        directory "moderate/notices", "app/views/moderate/notices" if include?("notices")
+
+        # Just the field partial, for the "I only want to restyle the fields" path.
+        # Guarded by File.exist? so the generator doesn't fail if the partial isn't
+        # part of the shipped set in a given version.
+        if include?("form") && !include?("notices")
+          partial = "moderate/notices/_form.html.erb"
+          copy_file partial, "app/views/#{partial}" if engine_view_exists?(partial)
+        end
+
+        # The engine layout (only if one ships under layouts/moderate).
+        if include?("layout")
+          directory "layouts/moderate", "app/views/layouts/moderate" if engine_view_exists?("layouts/moderate")
+        end
+      end
+
+      private
+
+      # True when the user asked for a given view group (case-insensitive).
+      def include?(group)
+        options[:views].map(&:to_s).include?(group)
+      end
+
+      # Whether a given path exists under the engine's view source_root, so we only
+      # try to copy templates that actually ship in this version.
+      def engine_view_exists?(relative_path)
+        File.exist?(File.join(self.class.source_root, relative_path))
+      end
+    end
+  end
+end