i18n_proofreading 0.12.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22fd6bf49d89c237346f9d8a2a5bc10314e0eab0fd8401dcca45dd96278ca62b
-  data.tar.gz: ba87b38138192aa1d850203839268109f1fc916c3e12160aa439f703f943336a
+  metadata.gz: 1018fa5f4f5be802e224bfc1a8bf5e93b1cff5c9122e854327792a9ffc89c0eb
+  data.tar.gz: 48b4c23cef0d8aac0ba47f996be007b259d3354fffa6065a1fea5f820b4802eb
 SHA512:
-  metadata.gz: 9d22947ee3ec8bb759537acbdee15e0d1520427f948499cd1cdc9af43eb4b0cf82ca30f35c562d02c4e0bada7813f8215a6ca071ecdb393563b7fca22581177e
-  data.tar.gz: d71f01a6a53c301f5f15453bdcdc8015ffefedcbd442c08ae0638301591496545776f2c98b424d68ad1b7777f5ea7f682b01c5de83bcba5e60e7a7fab0112d74
+  metadata.gz: cb442c1774c324987f44e8a347f74f061cd7ee64388df006f77b4a7d94ff6b6e57844303190f9fce36d7f556d7391160a1ef611e2424fe9a2a090d78638f16df
+  data.tar.gz: 3094f3c4160701c912116a499be621486b1f718168450b8030956bb43d3b1864576e7a278a95e948552444969c45835b150f7a05cd50106408bd9b3dfa381587

data/AGENTS.md

@@ -5,7 +5,7 @@ Instructions for coding agents. Two audiences:
 - **[Installing i18n_proofreading into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add in-context translation review or a way for someone to suggest better wording.
 - **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
 
-Requirements: Ruby >= 3.2, Rails >= 7.1. The widget needs the CSRF token from `csrf_meta_tags`, which a standard Rails layout already has.
+Requirements: Ruby >= 3.2, Rails >= 7.1 and < 9. The widget needs the CSRF token from `csrf_meta_tags`, which a standard Rails layout already has.
 
 **Read this first: the gem never writes to your locale files, and it is not a production tool.** Both are deliberate, and both are covered below.
 
@@ -137,6 +137,11 @@ The tool's own UI ships in 26 languages, RTL mirrored, and follows system light/
 
 ## Working on the gem itself
 
+The development toolchain is pinned to Ruby 4.0.5 in `mise.toml`. Do not use
+macOS's `/usr/bin/ruby`. In shells, hooks, or automation where mise activation
+is uncertain, explicitly prepend the configured Ruby, for example
+`PATH="$(mise where ruby)/bin:$PATH" bundle exec rake test`.
+
 ```bash
 bundle exec rake test            # minitest, dummy app under test/dummy
 bundle exec rubocop              # must be clean

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.0.1] - 2026-08-11
+
+- **A failing `on_submit` hook no longer turns a saved suggestion into a 500.**
+  The failure is logged after persistence, so host notifications cannot make
+  the review submission appear lost.
+- **Stored page context is now privacy-filtered.** Only bounded HTTP(S) URLs
+  without credentials, query strings, or fragments are retained.
+
+## [1.0.0] - 2026-08-11
+
+- **The documented integration surface is now the stable 1.x contract.**
+  `I18nProofreading.configure`, every generated configuration option,
+  `mount_i18n_proofreading`, `i18n_proofreading_tag`, the toggle parameter,
+  `I18nProofreading::Suggestion`'s documented fields/status helpers/scopes, and
+  the `on_submit` callback will follow semantic versioning. Engine controllers,
+  partials, CSS classes and widget internals remain private implementation.
+- **Hosts that load Action View from an initializer boot normally.** `TagHelper`
+  is required from `lib` before the engine registers its Action View load hook,
+  rather than relying on an `app/helpers` autoload that Rails may not have set
+  up yet. A dummy-host initializer now reproduces that early load on every test
+  boot. The helper constant and `i18n_proofreading_tag` API are unchanged.
+- Supported combinations are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1.
+  Rails now has a `< 9` upper bound: future Rails majors must pass the suite
+  before Bundler treats them as supported.
+- Added a security policy and documented the data a suggestion stores, the
+  production-off default, private vulnerability reporting, and host-owned
+  retention/deletion. Upgrading from 0.12.1 requires no migration or config
+  change.
+- Release validation now runs the normal and browser suites, RuboCop, the
+  widget syntax check and gem build on Ruby 4.0; it verifies the published
+  version and creates the GitHub Release. Generator tests now write only under
+  ignored root `tmp/`, so running the suite no longer rewrites tracked fixtures.
+
 ## 0.12.1
 
 - **The demo suggestions now teach the review contract.** Pending explains the
@@ -72,8 +107,6 @@
   does, so a uuid-keyed host gets a uuid table.
 - A `BackboneTest` now fails the build on any of the above regressing.
 
-## [Unreleased]
-
 ## [0.10.6]
 
 - Added `AGENTS.md`: install and integration instructions written for coding

data/README.md

@@ -46,8 +46,8 @@ No layout change needed — the widget injects itself into HTML responses.
 > `%w[development staging]`, and the review dashboard defaults to development
 > only. This is not a production tool.
 
-Ruby >= 3.2 · Rails >= 7.1 · CSRF token comes from `csrf_meta_tags`, already in
-a standard Rails layout.
+Ruby 3.2–4.0 · Rails 7.1–8.1 · CSRF token comes from `csrf_meta_tags`, already
+in a standard Rails layout.
 
 Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
 steps in the order an agent needs them, the gates it tends to get wrong, and the
@@ -273,6 +273,36 @@ to use the localized `i18n_proofreading.pill` key.
 
 </details>
 
+## Compatibility and public API
+
+Starting with 1.0, these documented integration points follow semantic
+versioning: incompatible changes wait for a new major version, while a
+deprecation normally ships in a preceding minor release.
+
+- `I18nProofreading.configure` and the configuration options listed above.
+- `mount_i18n_proofreading at:` and the mounted dashboard root.
+- `i18n_proofreading_tag` for hosts that disable automatic injection.
+- The configured toggle parameter and its `true` / `false` behavior.
+- `I18nProofreading::Suggestion` fields documented under Reviewing
+  suggestions, `STATUSES`, prefixed status helpers/scopes, and `newest_first`.
+- `on_submit`, called with the saved suggestion.
+
+Engine controllers, view partials, CSS classes, generated HTML structure, and
+the JavaScript object behind the widget are implementation details. Integrate
+through the APIs above rather than reopening or linking to those internals.
+
+Supported versions are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1. The gem
+depends on Rails `< 9`; support for a future Rails major is released after that
+major passes the compatibility and browser suites.
+
+### Upgrading from 0.12.1
+
+Change the version requirement and run `bundle update i18n_proofreading`. No
+database migration, generator, initializer change, or data rewrite is needed.
+The `I18nProofreading::TagHelper` constant and `i18n_proofreading_tag` behavior
+are unchanged; only the helper's internal load location moved so hosts that
+configure Action View during initialization can boot reliably.
+
 ## Security
 
 - **Gated on the server** for every marker, endpoint, and injection. Setting
@@ -286,6 +316,12 @@ to use the localized `i18n_proofreading.pill` key.
   survives Turbo visits.
 - **Rate-limited per IP** on the submission endpoint (30/min by default,
   Rails 7.2+).
+- **Host-owned review data.** A row may contain translated text, proposed text,
+  a comment, page URL, and optional author fields. The host controls access,
+  backups, retention, and deletion.
+
+Report vulnerabilities privately through the process in
+[SECURITY.md](SECURITY.md), not through a public issue.
 
 ## Development
 
@@ -296,7 +332,8 @@ bundle exec rake test:system  # browser tests (headless Chrome)
 bundle exec rubocop
 ```
 
-Tests run against a dummy Rails app in `test/dummy`.
+Tests run against a dummy Rails app in `test/dummy`. CI covers Ruby 3.2–4.0
+against Rails 7.1–8.1, plus the real browser flow on Ruby 4.0.
 
 ## One family
 

data/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released for the latest 1.x version. If a report also
+affects the newest 0.x release, a backport may be published when the fix is
+small and the affected application cannot upgrade immediately.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/i18n_proofreading/security/advisories/new)
+and include the affected version, a minimal reproduction, impact, and any known
+workaround. Credentials, session cookies, private application URLs, customer
+text, and production database contents should not be included.
+
+Public disclosure should wait until a fixed version is available and affected
+users have had a reasonable opportunity to upgrade.
+
+## Data and deployment boundary
+
+The proofreading widget is enabled only in development and staging by default.
+Adding production to `enabled_environments` is unsupported: key marking changes
+rendered application text and the suggestion endpoint is intended for trusted
+review environments.
+
+A suggestion can store its translation key, locale, current and proposed text,
+comment, page URL, status, timestamps, and optional host-provided author id and
+label. Host applications own that data, its backups, retention period, access
+controls, and deletion. Delete a suggestion with ordinary Active Record when a
+reviewer or application policy requires erasure:
+
+```ruby
+I18nProofreading::Suggestion.find(id).destroy!
+```
+
+The mounted dashboard is independently protected by `authorize_admin`. Outside
+development it fails closed until the host explicitly grants access.

data/app/controllers/concerns/i18n_proofreading/request_context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module I18nProofreading
   # Who is asking, and the gates that answer it.
   #
@@ -37,5 +39,23 @@ module I18nProofreading
 
       @current_author = I18nProofreading.config.current_user.call(request)
     end
+
+    # Browser URLs can carry password-reset tokens, signed ids, and campaign
+    # details in their query or fragment. Store only a bounded HTTP(S) location
+    # without credentials before it reaches the suggestion table.
+    def clean_page_url(value)
+      raw = value.to_s
+      return if raw.blank? || raw.length > 2_048
+
+      uri = URI.parse(raw)
+      return unless %w[http https].include?(uri.scheme&.downcase)
+      return if uri.host.blank? || uri.userinfo.present?
+
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s.first(255)
+    rescue URI::InvalidURIError
+      nil
+    end
   end
 end

data/app/controllers/i18n_proofreading/submissions_controller.rb

@@ -37,10 +37,11 @@ module I18nProofreading
 
     def create
       suggestion = Suggestion.new(suggestion_params)
+      suggestion.page_url = clean_page_url(suggestion.page_url)
       attribute_author(suggestion)
 
       if suggestion.save
-        I18nProofreading.config.on_submit.call(suggestion)
+        notify_host(suggestion)
         head :created
       else
         render json: { errors: suggestion.errors.full_messages }, status: :unprocessable_entity
@@ -49,6 +50,15 @@ module I18nProofreading
 
     private
 
+    # The host's hook must never turn a saved suggestion into a 500 — the
+    # suggestion is in the database; notification failures are the host's
+    # logs' problem.
+    def notify_host(suggestion)
+      I18nProofreading.config.on_submit.call(suggestion)
+    rescue StandardError => e
+      Rails.logger.error("i18n_proofreading: on_submit hook raised #{e.class}: #{e.message}")
+    end
+
     def attribute_author(suggestion)
       author = current_author
       return unless author

data/{app/helpers → lib}/i18n_proofreading/tag_helper.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 module I18nProofreading
-  # Lets a host place the widget explicitly (`<%= i18n_proofreading_tag %>` at the end
-  # of a layout) instead of relying on auto-injection. Renders nothing unless the
-  # tool is available for the current request.
+  # Lets a host place the widget explicitly (`<%= i18n_proofreading_tag %>` at
+  # the end of a layout) instead of relying on auto-injection. This lives under
+  # lib and is required before the engine registers its Action View load hook:
+  # a host initializer may load Action View before Rails sets up application
+  # autoloaders, when an app/helpers constant cannot be resolved yet.
   module TagHelper
     def i18n_proofreading_tag
       return ''.html_safe unless I18nProofreading.available?(request)

data/lib/i18n_proofreading/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18nProofreading
-  VERSION = '0.12.1'
+  VERSION = '1.0.1'
 end

data/lib/i18n_proofreading.rb

@@ -4,6 +4,7 @@ require 'i18n_proofreading/version'
 require 'i18n_proofreading/configuration'
 require 'i18n_proofreading/marking'
 require 'i18n_proofreading/widget'
+require 'i18n_proofreading/tag_helper'
 require 'i18n_proofreading/middleware'
 require 'i18n_proofreading/seeds'
 require 'i18n_proofreading/engine'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: i18n_proofreading
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 1.0.1
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 description: |
   A mountable Rails engine that renders each translation alongside its i18n key
   in development and staging, lets reviewers click any string in the running app
@@ -39,13 +45,13 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - app/controllers/concerns/i18n_proofreading/request_context.rb
 - app/controllers/i18n_proofreading/application_controller.rb
 - app/controllers/i18n_proofreading/dashboard_controller.rb
 - app/controllers/i18n_proofreading/submissions_controller.rb
 - app/controllers/i18n_proofreading/suggestions_controller.rb
 - app/controllers/i18n_proofreading/widgets_controller.rb
-- app/helpers/i18n_proofreading/tag_helper.rb
 - app/models/i18n_proofreading/application_record.rb
 - app/models/i18n_proofreading/suggestion.rb
 - app/views/i18n_proofreading/shared/_dashboard.html.erb
@@ -91,6 +97,7 @@ files:
 - lib/i18n_proofreading/marking.rb
 - lib/i18n_proofreading/middleware.rb
 - lib/i18n_proofreading/seeds.rb
+- lib/i18n_proofreading/tag_helper.rb
 - lib/i18n_proofreading/version.rb
 - lib/i18n_proofreading/widget.js
 - lib/i18n_proofreading/widget.rb
@@ -101,6 +108,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/yshmarov/i18n_proofreading
   changelog_uri: https://github.com/yshmarov/i18n_proofreading/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yshmarov/i18n_proofreading/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -116,7 +124,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: 'In-context i18n proofreading for Rails: click any translated string and
   suggest a fix.'