permittable 0.14.0 → 0.15.1

data/lib/permittable.rb

@@ -1041,9 +1041,13 @@ module Permittable
         found = Date._parse(value)
         return [:error, "invalid_type"] unless complete_date?(found)
         return cast_date_instant(value, found) if names_an_instant?(found)
-        # No time found, but an offset may have been dropped ("5/9/2026
-        # -0500"), which :datetime refuses too.
-        return [:error, "invalid_type"] if !plain && offset_misread?(value, found)
+
+        # No time found, but a zone or offset may have been dropped
+        # ("5/9/2026 -0500", "2026-09-05 EST") or an hour with it
+        # ("2026-09-05T10"), which :datetime refuses or reads the same way.
+        if !plain && (dropped = dropped_tail(value, found))
+          return date_at_midnight(*dropped)
+        end
 
         # Built from the components rather than re-running Date.parse, which
         # would parse the same string a second time — and Date.parse is the
@@ -1082,10 +1086,13 @@ module Permittable
     # ruled out the ISO forms cast_datetime reads without one; :datetime's
     # reading of it is then the same, with one parse fewer.
     def cast_date_instant(value, found = nil)
-      status, instant = found ? cast_parsed_datetime(value, found) : cast_datetime(value)
-      return [:error, "invalid_type"] unless status == :ok && instant == instant.beginning_of_day
+      date_at_midnight(*(found ? cast_parsed_datetime(value, found) : cast_datetime(value)))
+    end
 
-      [:ok, Date.new(instant.year, instant.month, instant.day)]
+    # The Date of an instant read from a String when it is midnight UTC.
+    def date_at_midnight(status, instant)
+      date = date_of_instant(instant) if status == :ok
+      date ? [:ok, date] : [:error, "invalid_type"]
     end
 
     # The date a Time or DateTime IS, or nil: its UTC date when it is
@@ -1167,7 +1174,9 @@ module Permittable
     # parts, shared with cast_date_instant so a :date need not parse twice.
     def cast_parsed_datetime(value, found)
       return [:error, "invalid_type"] unless complete_date?(found) && honoured_zone?(found)
-      return [:error, "invalid_type"] if offset_misread?(value, found)
+
+      dropped = dropped_tail(value, found)
+      return dropped if dropped
 
       [:ok, DateTime.parse(value, true, Date::GREGORIAN).to_time.utc]
     rescue ArgumentError, RangeError
@@ -1236,23 +1245,126 @@ module Permittable
       (zone.start_with?("-") ? -1 : 1) * ((hours * 3600) + (minutes * 60))
     end
 
-    # Whether a date's trailing offset was taken for its time of day
-    # ("Sep 5 2026 -05:00" reports 05:00, "2026-09-05 UTC-05:00" too) or
-    # dropped without a trace ("5/9/2026 -0500", "2026-09-05 +5"), outside
-    # the ISO form midnight_at_offset reads. The tail is the culprit when the
-    # parser found no zone and the String without it names the same date and
-    # no time. Only a String that ends in a signed number and either got an
-    # hour or has a space before the number is parsed again, so a plain
-    # "2026-09-05" is not.
-    def offset_misread?(value, found)
-      return false if found.key?(:zone)
+    # An ISO date, then a "T": what follows is an ISO time, so a parse that
+    # found no hour ("2026-09-05T10", "T1030", "T10Z") dropped it.
+    ISO_DATE_T_START = /\A\s*\d{4}(-?)\d{2}\1\d{2}[Tt]/
+
+    # Trailing words, set apart by a space: a zone name ("EST", "Eastern
+    # Standard Time", "W. Europe Standard Time") or a day or era word. The
+    # first word may be one letter, which is a military zone or the ISO "T"
+    # and so no zone here, but still stands where an hour was lost.
+    ZONE_NAME_TAIL = /(?<=\s)[[:alpha:]](?:\.|[[:alpha:]]+)?[[:alpha:].]*(?:\s+[[:alpha:].]+)*\z/
+
+    # An era word at the start of such a tail: the parser reads it with the
+    # date ("Sep 5 2026 BC" is the year -2025), so it is not what follows.
+    ERA_WORD = /\A(?:a\.?\s?d\.?|c\.?\s?e\.?|b\.?\s?c\.?(?:\s?e\.?)?)(?:\s+|\z)/i
 
-      tail = SIGNED_TAIL.match(value) or return false
-      return false unless tail[1] || found.key?(:hour)
+    # What ends a date the way git, `date` and Time#to_s write it, with the
+    # offset after the year: "Sat Sep 5 10:00:00 2026", "Sep 5 10:00 2026".
+    TIME_THEN_YEAR = /\d:\d{2}(?::\d{2}(?:[.,]\d+)?)?\s+\d{4}\s*\z/
+    private_constant :ZONE_NAME_TAIL, :ERA_WORD, :TIME_THEN_YEAR
 
-      rest = Date._parse(tail.pre_match)
-      complete_date?(rest) && !rest.key?(:hour) &&
-        rest.values_at(:year, :mon, :mday) == found.values_at(:year, :mon, :mday)
+    # What Date._parse did with the END of a date or date-time String when it
+    # dropped or misplaced it, as nil when it did neither, or the result
+    # ([:ok, instant] or [:error, "invalid_type"]) the String must be given:
+    #
+    # - an hour after an ISO "T" it did not find ("2026-09-05T10");
+    # - a trailing offset taken for a time of day ("Sep 5 2026 -05:00",
+    #   "2026-09-05 10 -05:00", "2026-09-05 UTC-05:00") or dropped without a
+    #   trace ("5/9/2026 -0500", "12:00 2026-09-05 -05:00"), outside the ISO
+    #   form midnight_at_offset reads. An offset after "10:00:00 2026" is the
+    #   exception: that is git's and ctime's format, which puts it after the
+    #   year, so it is read, like a zone name;
+    # - a trailing zone NAME, which it reads only next to a time of day:
+    #   "2026-09-05 EST" is midnight at -05:00 and "Sat Sep 5 10:00:00 2026
+    #   EST" 10:00 there. A name it does not know is refused like any other
+    #   zone (honoured_zone?), and so is ANY other word after a complete date
+    #   ("2026-09-05 noon"), since all it can be is a zone. A day name and an
+    #   era word are what the parser reads as part of the date, not a zone.
+    #
+    # The tail is the culprit when the parser found no zone and the String
+    # without it names the same date (and time). Only a String that ends in a
+    # signed number or a word is parsed again, so a plain "2026-09-05" is not.
+    def dropped_tail(value, found)
+      return [:error, "invalid_type"] if !found.key?(:hour) && ISO_DATE_T_START.match?(value)
+      return if found.key?(:zone)
+
+      if (tail = SIGNED_TAIL.match(value))
+        # An offset glued to a zone name with no time ("2026-09-05 GMT+5") is
+        # read below as midnight at that offset; one glued to a date is a
+        # part of it ("2026-09-05" ends in "-05").
+        named = !tail[1] && !found.key?(:hour) && /\s[[:alpha:]]+\z/.match(tail.pre_match)
+        return unless tail[1] || found.key?(:hour) || named
+
+        rest = Date._parse(tail.pre_match)
+        return unless same_date?(rest, found)
+        return glued_zone(named, tail[0].strip, found) if named
+
+        git_style = tail[1] && found.key?(:hour) && TIME_THEN_YEAR.match?(tail.pre_match) && same_time?(rest, found)
+        git_style ? instant_in_zone(tail.pre_match, tail[0].strip) : [:error, "invalid_type"]
+      elsif (tail = ZONE_NAME_TAIL.match(value))
+        pre = tail.pre_match
+        text = tail[0]
+        if (era = ERA_WORD.match(text))
+          pre += era[0]
+          text = era.post_match
+        end
+        # The era is part of the date, so the hour a lost one hid is looked
+        # for before it ("2026-09-05 10 A.D.", "2026-09-05 10 AD EST").
+        head = era ? Date._parse(tail.pre_match) : nil
+        return same_time?(head, found) ? nil : [:error, "invalid_type"] if text.empty?
+
+        rest = Date._parse(pre)
+        return unless same_date?(rest, found)
+
+        zone = Date._parse("00:00 #{text}")
+        return unless zone.key?(:zone) # a day name
+        # The hour the tail made the parser lose ("2026-09-05 10 EST").
+        return [:error, "invalid_type"] unless same_time?(head || rest, found)
+        # A single letter is a military zone, which is no zone here: alone it
+        # is nothing ("2026-09-05 a", "A."), but the rest of an initial-led
+        # name Ruby did not know ("W. Europe") is dropped, so it is refused
+        # like any other word it does not know.
+        return text.match?(/\A[[:alpha:]]\.?\z/) ? nil : [:error, "invalid_type"] if zone[:zone].length == 1
+
+        instant_in_zone(pre, text)
+      end
+    end
+
+    # A signed offset after a zone name ("GMT+5", "UTC+0530") is that zone to
+    # Ruby when it reads it next to a time, so the String is midnight at it.
+    # A name it does not read whole ("EST+5") or honour ("UTC+99") is refused.
+    # What comes before the zone is held to the rules of any date String: no
+    # hour a lost tail hid ("2026-09-05 10 AD GMT+5"), no second zone, and the
+    # offset is hours ("+5", "+05") or hhmm with minutes a minute ("+0530").
+    def glued_zone(word, offset, found)
+      zone = "#{word[0].strip}#{offset}"
+      pre = Date._parse(word.pre_match)
+      return [:error, "invalid_type"] unless offset.match?(GLUED_OFFSET) && Date._parse("00:00 #{zone}")[:zone] == zone
+      return [:error, "invalid_type"] unless same_time?(pre, found) && !pre.key?(:zone) && dropped_tail(word.pre_match, pre).nil?
+
+      instant_in_zone(word.pre_match, zone)
+    end
+
+    # The wall clock `date` names, as it is read in the zone `text` names:
+    # [:ok, instant], or an error when Ruby cannot honour the zone.
+    def instant_in_zone(date, text)
+      zone = Date._parse("00:00 #{text}")
+      return [:error, "invalid_type"] unless zone.key?(:zone) && honoured_zone?(zone)
+
+      [:ok, DateTime.parse(date, true, Date::GREGORIAN).to_time.utc - zone[:offset]]
+    end
+
+    def same_time?(rest, found)
+      TIME_PARTS.all? { |part| rest[part] == found[part] }
+    end
+
+    TIME_PARTS = %i[hour min sec sec_fraction].freeze
+    GLUED_OFFSET = /\A[+-](?:\d{1,2}|\d{2}[0-5]\d)\z/
+    private_constant :TIME_PARTS, :GLUED_OFFSET
+
+    def same_date?(rest, found)
+      complete_date?(rest) && rest.values_at(:year, :mon, :mday) == found.values_at(:year, :mon, :mday)
     end
 
     # Presets only make sense on String input; a non-String value (JSON
@@ -1446,13 +1558,17 @@ module Permittable
     end
 
     # What an exported enum lists for one member: the cast value, re-encoded
-    # as JSON — except a :date/:datetime member authored as a String, which
-    # is published AS WRITTEN. Re-encoding a cast Time prints whole seconds,
-    # so "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value
-    # the server refuses. The authored String went through the very cast a
-    # request does, so the server accepts it by construction.
+    # as JSON — except a :datetime member authored as a String, which is
+    # published AS WRITTEN. Re-encoding a cast Time prints whole seconds, so
+    # "2026-09-05T10:00:00.25Z" was published as "…10:00:00Z", a value the
+    # server refuses. The authored String went through the very cast a request
+    # does, so the server accepts it by construction. A :date member is
+    # re-encoded: a Date has no digits to lose, and the String as written
+    # ("Sep 6, 2026", "2026-09-05T00:00:00Z") is a date the server reads but
+    # not one `format: date` accepts, so it is published as the YYYY-MM-DD
+    # the server compares against.
     def published_in_member(type, member, value)
-      member.is_a?(String) && %i[date datetime].include?(type) ? member : value
+      member.is_a?(String) && type == :datetime ? member : value
     end
 
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
@@ -1799,7 +1915,7 @@ module Permittable
     end
 
     # `published` is stored only where it differs from the cast members (a
-    # String-authored :date/:datetime member), so it is read as an override.
+    # String-authored :datetime member), so it is read as an override.
     def cast_in_members!(field, members)
       status, cast, published = Coercion.cast_in_members(field[:type], members, nullable: field[:nullable])
       unless status == :ok
@@ -1896,6 +2012,12 @@ module Permittable
     def validate_json_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
+
+      # A request sending "" for a nullable :json field is the explicit null
+      # the walker reads it as, so a blank authored value is that nil, as a
+      # nullable scalar's is (see validate_authored_value!).
+      return field[opt] = nil if field[:nullable] && Coercion.absent_value?(field[opt])
+
       raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
 
       status, read = AuthoredValues.read_json(field, field[opt])
@@ -2351,6 +2473,11 @@ module Permittable
     # rescue_from until the app includes them, and a rule that needs one of
     # them would otherwise load and then not run: raise at class load, naming
     # the module. Other hosts (a plain class, a duck) are left as they are.
+    # Only the rule's OWN declared mode is read, never Permittable.mode: that
+    # is usually set by an initializer, and an app must not stop booting over
+    # it. The effective mode can only add a requirement, so an action it makes
+    # monitored without a before_action is left to Audit.inert?, which reports
+    # it as not covered.
     def permittable_ensure_runnable!(rule)
       return unless defined?(::ActionController::Metal) && self < ::ActionController::Metal
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-09 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport