activestorage-validator 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b66feb405437ad34641613c818d1fee5d8130235ab77b30ab07630ca7a09560
-  data.tar.gz: 00417b87e52603376cca1afc253e336b8ac5a090fbdbb386f43ae2062a73bdb0
+  metadata.gz: acc9fae7338e419736df276e25e94e198cdc8a0ca9a2b80210c3175d684f5f22
+  data.tar.gz: 6b9be22b0d25c70bcf08cc51a05f9443982963d7e42e3817b90c60a596e5e071
 SHA512:
-  metadata.gz: 457cd27983de69c7d3e1e0f9c9226fb5b67410be17e4f64132220ce0953a4c4a9345eed292628343eb4f373bbdd83aab501f6036eb689a2627f86cff22207c49
-  data.tar.gz: a7ea46c6d09ea311b7329bc63b94355c543a568a562d8db413f447a479238aae295d42edbcf29665969b4083af97624ad16a8d984a9e41120fee2dac68135f92
+  metadata.gz: 57e1e9cd4353cfcb2aaeee8a2eef4bbedfe49b3382a3cacc7281fa1e5ec5ca1aa10158465a42e6eff8c2dbfd375b16f9ddb26c3027d1b337ca8fd0b41824c94b
+  data.tar.gz: 597d5cd7f32091fcf00a196fa4bd9d7404e5f129db45d0235c70768a01167d47ae9ec361b635b2732add9ba8be45c2bb2fef6db5a4b67e676130dfe7cf9fd13a

data/README.md

@@ -117,6 +117,23 @@ en:
 - Some features may not work depending on your ActiveStorage or Rails version.
 - Validation error messages are I18n compatible and support interpolation keys as described above.
 
+## Agent skill
+
+This repo ships an [agent skill](skills/activestorage-validator/) (`SKILL.md`,
+plus a Japanese `SKILL-ja.md`) that teaches coding agents when and how to apply
+`activestorage-validator`. Install it into your project with the GitHub CLI:
+
+```sh
+gh skill install aki77/activestorage-validator
+```
+
+> `gh skill` is currently a GitHub CLI preview feature.
+
+Alternatively, if your project already pulls `activestorage-validator` in via
+Bundler, the [bundler-skills](https://github.com/aki77/bundler-skills) plugin
+auto-syncs this skill on `bundle install` — keeping the skill version locked to
+the gem version.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub via [issues](https://github.com/aki77/activestorage-validator/issues) or [pull requests](https://github.com/aki77/activestorage-validator/pulls).

data/activestorage-validator.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) || f.match(%r{^skills/.*-ja\.md$}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

data/lib/activestorage/validator/version.rb

@@ -1,5 +1,5 @@
 module ActiveStorage
   module Validator
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

data/skills/activestorage-validator/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: activestorage-validator
+description: "Validate ActiveStorage attachments (content type, file size, file extension) with the activestorage-validator gem's `blob` validator. Use when adding validations to has_one_attached / has_many_attached attributes."
+---
+
+# activestorage-validator
+
+A Rails gem that adds a `blob` validator for ActiveStorage attachments. It
+validates content type, file size, and file extension on both
+`has_one_attached` and `has_many_attached` attributes.
+
+## First: determine applicability
+
+Use this gem **only** for validating ActiveStorage attachments. For ordinary
+(non-attachment) attributes, use the standard Rails validators (`presence`,
+`length`, `numericality`, etc.).
+
+| What you validate | Tool |
+| --- | --- |
+| ActiveStorage attachment (content type / size / extension) | **`blob:` validator (this gem)** |
+| Plain string/number/boolean columns | Standard Rails validators |
+| Presence of the attachment itself | `presence: true` (works alongside `blob:`) |
+
+There is no special read path — declare `validates ..., blob: { ... }` and the
+attachment is validated like any other Rails validation on `save`/`valid?`.
+
+## Usage
+
+Declare validations on the model with the `blob:` validator.
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+  has_many_attached :photos
+
+  # Allow only web image files (PNG, JPEG, GIF, WebP)
+  validates :avatar, presence: true, blob: { content_type: :web_image }
+
+  # Allow only JPEG/PNG, up to 5MB per file
+  validates :photos, presence: true, blob: {
+    content_type: ["image/png", "image/jpg", "image/jpeg"],
+    size_range: 1..(5.megabytes)
+  }
+
+  # Regexp content_type + required extension (AND condition)
+  validates :audio, blob: { content_type: "audio/mpeg", extension: %w[mp3] }
+end
+```
+
+> For `has_many_attached`, every option (including `size_range`) is applied to
+> **each file individually**.
+
+## Options (all optional, combine freely)
+
+| Option | Accepts | Notes |
+| --- | --- | --- |
+| `content_type` | Symbol / Array / Regexp / String | Allowed MIME type(s). See matching below. |
+| `size_range` | Range | Allowed byte size, e.g. `1..(5.megabytes)`. |
+| `extension` | String / Array | Allowed filename extension(s). |
+
+### `content_type` matching
+
+- **`:web_image`** — special-cased to `ActiveStorage.web_image_content_types`
+  (PNG, JPEG, GIF, WebP). Use this instead of `:image` when you want only
+  browser-safe images.
+- **Other Symbol** (`:image`, `:audio`, `:video`, `:text`) — calls the
+  ActiveStorage built-in predicate `blob.image?` / `blob.audio?` / etc.
+- **Array** — `["image/png", "image/jpeg"]`: exact membership of the blob's
+  content type in the list.
+- **Regexp** — `%r{^image/}`: matched against the blob's content type.
+- **String** — `"application/pdf"`: exact equality.
+
+### `extension` matching
+
+- Accepts a String (`"mp3"`) or Array (`%w[mp3 m4a]`).
+- Leading dot is optional (`"mp3"` == `".mp3"`).
+- Case-insensitive (`PHOTO.JPG` matches `extension: "jpg"`).
+- **A file with no extension is always rejected** when `extension` is set.
+- When combined with `content_type`, both must pass (AND). E.g.
+  `{ content_type: "audio/mpeg", extension: %w[mp3] }` rejects a `.wav` file
+  even if its MIME type happens to be `audio/mpeg`.
+
+## I18n error messages
+
+Errors are I18n-compatible. Error types and their interpolation keys:
+
+| Error type | Interpolation keys | When |
+| --- | --- | --- |
+| `content_type` | `filename` | content type not allowed |
+| `min_size_error` | `filename`, `min_size` | smaller than `size_range.min` |
+| `max_size_error` | `filename`, `max_size` | larger than `size_range.max` |
+| `extension` | `filename`, `extension` | extension not allowed (or missing) |
+
+`min_size` / `max_size` are humanized (`ActiveSupport::NumberHelper.number_to_human_size`).
+`extension` is the allowed list joined by `, `.
+
+```yaml
+# config/locales/en.yml
+en:
+  errors:
+    messages:
+      content_type: "%{filename} has an invalid content type"
+      min_size_error: "%{filename} is too small (minimum is %{min_size})"
+      max_size_error: "%{filename} is too large (maximum is %{max_size})"
+      extension: "%{filename} has an invalid file extension (allowed: %{extension})"
+```
+
+The gem ships default messages for 7 locales: `en`, `ja`, `de`, `es`, `fr`,
+`pl`, `pt-br`. Override them in your app's locale files using the keys above.
+
+## Behavior details
+
+- **Unattached values are skipped.** Validation returns early unless the
+  attachment is attached, so `blob:` does not enforce presence — add
+  `presence: true` separately if the attachment is required.
+- **Size boundaries are inclusive.** A blob is valid when
+  `size_range.min <= byte_size <= size_range.max`. Below min → `min_size_error`;
+  above max → `max_size_error`.
+- **Extension normalization** is `downcase` + strip a single leading dot; an
+  empty resulting extension (no extension on the file) fails.
+- Options are independent — omit any you don't need; only the present ones run.
+
+## Pitfalls
+
+- A file **without an extension** is rejected whenever `extension:` is set —
+  even if its content type is allowed. Don't set `extension:` if you accept
+  extension-less uploads.
+- For `has_many_attached`, `size_range` applies **per file**, not to the total.
+- `blob:` alone does **not** require an attachment; pair it with `presence: true`
+  when the upload is mandatory.
+- No special read/preload path exists — this is a plain `EachValidator`; it runs
+  on standard `valid?` / `save`.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: activestorage-validator
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - aki
 bindir: exe
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -115,6 +115,7 @@ files:
 - lib/activestorage/validator.rb
 - lib/activestorage/validator/blob.rb
 - lib/activestorage/validator/version.rb
+- skills/activestorage-validator/SKILL.md
 homepage: https://github.com/aki77/activestorage-validator
 licenses:
 - MIT
@@ -133,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: ActiveStorage blob validator.
 test_files: []