moderate 0.1.0 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c7f6fd1cfa1c2ba6b28e2d0b75ce803d0ae2eec002011b18a9a25b2b98ce6f
-  data.tar.gz: 71bab2651af6c3ff8520360281811b53d21a711496a9ef392334e8b2a59646b5
+  metadata.gz: 20519d26bf4bc96f23e6f679b3b175376700280e36f21fffa409230688526b25
+  data.tar.gz: 8abc344dcf72c577de12ba70dbf96895f008a041355a75308f815d8b267f5dd1
 SHA512:
-  metadata.gz: adfb034df21d5ecfa8fec498f34df2d6595d33033f05e7fb2832ec52f7c0012fa43806950b9c9d723cc0508563159972e57ceb051e3263ca0cfff11583bb9959
-  data.tar.gz: 2dd06af75442e89d39e18f44c7dc61e37030dfbee6406f5be096903418489f9061dea5262aeaa874431ec4c3ac82f3c93933036d7715e3255e6431715c6923ff
+  metadata.gz: 65f2ad5ae6dae9a4a1269900e67205cfedaa5f82ff3b87d218ac34dee0e05bdb417fd77289126c47c9cf372b0dfd710fc1fa5d455d1f1f256395d2ec4bc7e79c
+  data.tar.gz: 5d3a60adaef05e13b448c1563d3104423c2d94d63ae0b10c7f2432268188a745849ca29df9e99fdb4860670a4c4f3f6fe7eda8fa07a4dd4a8f47169eca97d3f8

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.2
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.simplecov

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices.
+# Coherent with the rest of the gem ecosystem (usage_credits, pricing_plans, …).
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Don't count the test suite itself toward coverage
+  add_filter "/test/"
+
+  # Don't count code that ISN'T unit-testable by this suite and would only distort
+  # the numbers:
+  #   - Generators + their templates: these run via `rails generate moderate:install`
+  #     / `moderate:views` in a real host, not in the engine's own unit suite. (The
+  #     migration template IS exercised indirectly — the dummy migrates a copy of it —
+  #     but the .erb itself is never loaded as Ruby here.)
+  #   - version.rb: a single constant; nothing to cover.
+  #   - The 0.x compatibility shims (text / text_validator / word_list): legacy
+  #     profanity-validator code kept only so `validates :field, moderate: true` from
+  #     0.x still loads (see README "Upgrading from 0.x"). They are NOT part of the
+  #     1.0 Trust & Safety surface this suite tests, so they shouldn't pull the 1.0
+  #     coverage number down.
+  add_filter "/lib/generators/"
+  add_filter "/lib/moderate/version.rb"
+  add_filter "/lib/moderate/text.rb"
+  add_filter "/lib/moderate/text_validator.rb"
+  add_filter "/lib/moderate/word_list.rb"
+
+  # Track Ruby files in the lib directory (gem source code)
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Minimum coverage thresholds to prevent coverage REGRESSION. These reflect what
+  # the current shipped suite actually exercises (line ~86%, branch ~65%): the
+  # primitives — models, concerns, services, adapters, the facade, the value objects —
+  # are thoroughly covered; the lower branch number is driven by the engine's
+  # CONTROLLERS (the public DSA notice form + the BYOUI moderation concern) and the
+  # async ClassifyJob, whose request/job paths the unit suite doesn't drive. The
+  # thresholds sit just under the current floor so the gate catches a real regression
+  # without failing on the existing baseline; raise them as request/job coverage grows.
+  minimum_coverage line: 80, branch: 60
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV["TEST_ENV_NUMBER"]
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n" + "=" * 60
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please read the `README.md` for a full overview of the gem's API and philosophy, and the `docs/` directory (`docs/configuration.md`, `docs/notifications.md`, `docs/compliance.md`, `docs/madmin.md`, `docs/dsa-notice-form.md`) for the detailed integration guides.
+
+This gem is part of a coherent ecosystem (`railsfast`, `goodmail`, `telegrama`, `usage_credits`, `pricing_plans`, `wallets`, `api_keys`). Match the ecosystem conventions exactly: a single `Moderate.configure do |config| … end` block, `has_*`/verb-style class macros, adapter objects + no-op-default hook procs, string class names constantized lazily, adaptive install migrations, Minitest with a `test/dummy` app, SimpleCov, and the README/docs voice.

data/Appraisals

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Test the minimum supported Rails version (matches the gemspec floor and the
+# README's "Rails 7.1+ schema" claim — the adaptive migration must work here).
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+# Test the latest Rails version — this is the default/main Gemfile anyway.
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -1,3 +1,111 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0.beta2] - 2026-07-10
+
+Second beta on the road to 1.0. Fixes beta1's async-adapter routing bug (the one
+that forced hosts to hand-roll their own enqueue), makes Active Storage
+attachments filterable with zero wiring, and gives `Flag` first-class close
+methods. Drop-in upgrade from beta1: no migrations, no breaking API changes —
+and hosts that worked around the ClassifyJob bug can now delete the workaround.
+
+### Fixed
+
+- **Async adapters now actually run in `Moderate::ClassifyJob`.** beta1's `:flag`
+  after_commit called `Moderate.classify` inline for *every* adapter — including
+  ones declaring `synchronous? == false` — so a remote moderation API ran its
+  network call inside the request that saved the content, and `ClassifyJob`
+  (whose docs promised this routing) was never enqueued by anything. The concern
+  now checks `config.adapter_async?(policy.adapter)` (new public helper, same
+  probe as the `:block` validator) and enqueues the job instead; the job re-reads
+  the persisted value and files the Flag itself. Hosts that worked around this by
+  enqueuing `ClassifyJob` themselves and short-circuiting
+  `moderation_field_changed_for_commit?` can delete both workarounds. (#3)
+
+### Added
+
+- **Active Storage attachments filter out of the box.** `moderates :avatar, with:
+  :your_image_adapter, mode: :flag` on a `has_one_attached` model needs zero extra
+  wiring now: the concern snapshots `attachment_changes` in a `before_save` (AR
+  dirty tracking can't see attachment writes, and Active Storage clears the
+  changes before after_commit), consumes the snapshot at commit time, and both
+  the concern and `ClassifyJob` treat an unattached `ActiveStorage::Attached`
+  proxy as blank (nothing to classify — covers purge-between-enqueue-and-run).
+  The three `moderation_field_*` seam overrides remain for richer cases. (#3)
+- **Flag close sugar.** `Flag#action!(note:, by: nil)` / `Flag#dismiss!(note:, by: nil)` —
+  model-level closes mirroring `Report#resolve!`/`#dismiss!`, so hosts stop hand-writing
+  status updates. `by:` stays nil for automated closes (don't fake a human in the audit
+  trail). Canonical automated use: dismiss a pending flag whose flagged content was
+  **superseded** (text edited, photo replaced/reverted) — left pending it keeps `flagged?`
+  true and mislabels the NEW content in any host UI keyed on it. (#4)
+
+## [1.0.0] - unreleased
+
+A complete, ground-up rewrite. `moderate` graduates from a single-purpose profanity
+validator (0.1.0) into a full **Trust & Safety** engine for Rails apps with user-generated
+content: report, block, filter, a moderation queue, appeals, and EU DSA / App Store / Google
+Play **aligned** primitives. (First cut shipped as `1.0.0.beta1`; second as `1.0.0.beta2`.)
+
+> **Breaking:** 1.0 keeps the gem name but is an entirely new API. The 0.x profanity
+> validator (`validates :field, moderate: true`) still loads for backward compatibility
+> (see _Upgrading from 0.x_), but everything else is new. Pin `~> 0.1` if you relied on the
+> old behavior and are not ready to adopt the new surface.
+
+### Added
+
+- **Reporting.** `Moderate::Report` plus the `has_reportable_content :fields` macro and
+  `Actor#report!(reportable, category:, details:)`. Reports and DSA notices share one model
+  and one queue (`intake_kind: "community" | "dsa"`).
+- **Blocking.** `Moderate::Block`, the `has_reporting_and_blocking` actor macro, and
+  `block!` / `unblock!` / `blocks?` / `blocked_by?` / `blocked_with?`. `Moderate.blocked_ids_for(user)`
+  is the bidirectional single source of truth you compose into feed/search/inbox queries.
+  Optional `config.on_block` teardown hook runs inside the block transaction.
+- **Content filtering.** The `moderates :field, mode: :off|:block|:flag, with: :adapter` macro
+  (and the equivalent `config.filter`), the offline multilingual `:wordlist` adapter (the only
+  built-in), the `classify(value) => Moderate::Result` adapter contract with
+  `config.register_adapter`, asynchronous classification via `Moderate::ClassifyJob`, and
+  ready-to-copy reference adapters for OpenAI omni-moderation and AWS Rekognition under
+  `examples/` (bring-your-own, never a dependency).
+- **Moderation queue & decisions.** `Moderate::Flag` and the service objects
+  `Moderate::Services::{IntakeReport, ResolveReport, ResolveFlag, IntakeAppeal, ResolveAppeal,
+  IntakeNotice}`. Decisions are taken under a row lock, re-check open state, apply enforcement
+  (remove content / ban) inside the transaction, and fire notifications outside it; the appeal
+  window and statement-of-reasons fields are stamped automatically.
+- **DSA-aligned primitives.** A mountable public **notice-and-action** form (Art. 16) you mount
+  at any path, **statement of reasons** (Art. 17), internal **appeals** (Art. 20), and
+  **transparency** counters (Art. 24). The notice form prefills from query params + the signed-in
+  user, locks auto-filled identity fields, and auto-detects `rails_cloudflare_turnstile`.
+- **Hooks (all no-op by default).** `config.audit`, `config.notify` (returns a delivery boolean
+  used to gate `decision_notified_at`), `config.on_block`, `config.ban_handler`, the
+  host-overridable `config.report_categories`, and `config.notice_human_verification_skip_if` /
+  `config.appeal_human_verification_skip_if` for native-app bot-gate carve-outs.
+- **Optional integrations**, all auto-detected at runtime via `defined?`/`respond_to?` and never
+  hard dependencies: madmin, goodmail, telegrama, noticed, rails_cloudflare_turnstile.
+- **Install tooling.** `rails generate moderate:install` writes a documented initializer and an
+  adaptive migration (uuid/bigint primary keys, jsonb/json/MySQL JSON columns); `moderate:views`
+  ejects the notice form for customization.
+
+### Changed
+
+- Taxonomies (report categories, DSA legal reasons, country codes) are now frozen model
+  constants with inclusion validations instead of DB `CHECK` constraints — adding or
+  customizing a category needs no migration.
+- External classifiers (OpenAI, image moderation) are reference adapters in `examples/`, not
+  shipped or loaded code — the gem core forces no service dependency on apps that never use it.
+- All "DSA-compliant" / "App Store compliant" language reframed to **DSA-aligned primitives**:
+  the gem ships the mechanisms the law and the stores require; your policies, response times,
+  and operations are still yours.
+
+### Upgrading from 0.x
+
+- The 0.x profanity validator still loads: `validates :field, moderate: true` continues to work
+  via compatibility shims, so existing apps keep validating. To adopt 1.0, add
+  `has_reporting_and_blocking` to your user model and `has_reportable_content` / `moderates` to your
+  content models, run `rails generate moderate:install`, and migrate.
+
 ## [0.1.0] - 2024-11-03
 
-- Initial release
+- Initial release (profanity validator).

data/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please read the `README.md` for a full overview of the gem's API and philosophy, and the `docs/` directory (`docs/configuration.md`, `docs/notifications.md`, `docs/compliance.md`, `docs/madmin.md`, `docs/dsa-notice-form.md`) for the detailed integration guides.
+
+This gem is part of a coherent ecosystem (`railsfast`, `goodmail`, `telegrama`, `usage_credits`, `pricing_plans`, `wallets`, `api_keys`). Match the ecosystem conventions exactly: a single `Moderate.configure do |config| … end` block, `has_*`/verb-style class macros, adapter objects + no-op-default hook procs, string class names constantized lazily, adaptive install migrations, Minitest with a `test/dummy` app, SimpleCov, and the README/docs voice.