claricle 0.1.0 → 0.2.0

data/lib/claricle/models/base.rb

@@ -0,0 +1,460 @@
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
+
+module Claricle
+  module Models
+    # The per-attribute checks `validate_deeply` runs beyond what lutaml
+    # validates on its own. Its own module because Base crosses RuboCop's
+    # class-length limit with this much of it inline -- measured, not
+    # assumed: folded back in, RuboCop reports Base at 111 lines against
+    # a limit of 100. Dropping the Marshal protocol did not change that.
+    module Validation
+      CORE_INSTANCE = ::Object.instance_method(:instance_of?)
+      KIND_OF = ::Object.instance_method(:is_a?)
+      CLASS_OF = ::Object.instance_method(:class)
+      FROZEN = ::Object.instance_method(:frozen?)
+      ARRAY_ELEMENTS = ::Array.instance_method(:each)
+      ARRAY_FIRST = ::Array.instance_method(:first)
+      ARRAY_SIZE = ::Array.instance_method(:size)
+      private_constant :CORE_INSTANCE, :KIND_OF, :CLASS_OF, :FROZEN,
+                       :ARRAY_ELEMENTS, :ARRAY_FIRST, :ARRAY_SIZE
+
+      private
+
+      def core_instance?(value, type)
+        CORE_INSTANCE.bind_call(value, type)
+      end
+
+      def inherits_from?(value, type)
+        KIND_OF.bind_call(value, type)
+      end
+
+      def class_of(value)
+        CLASS_OF.bind_call(value)
+      end
+
+      def object_frozen?(value)
+        FROZEN.bind_call(value)
+      end
+
+      def each_array(value, &)
+        ARRAY_ELEMENTS.bind_call(value, &)
+      end
+
+      def array_first(value)
+        ARRAY_FIRST.bind_call(value)
+      end
+
+      def array_size(value)
+        ARRAY_SIZE.bind_call(value)
+      end
+
+      # One sentence for every one of these checks, and one place that
+      # knows lutaml's ValidationError carries exceptions rather than
+      # Strings -- handed bare Strings, its own `error_messages` blows
+      # up. Subclasses raise through here too.
+      def refuse(name, expectation, got)
+        raise Lutaml::Model::ValidationError,
+              [TypeError.new("#{name} expects #{expectation}, got #{got}")]
+      end
+
+      # A declared model attribute is only cast when it arrives as a hash
+      # from a document. Handed a wrong-typed object directly, lutaml stores
+      # it as-is and the failure surfaces much later as a NoMethodError.
+      def validate_types
+        self.class.attributes.each do |name, attribute|
+          validate_finite(name)
+          validate_default_bookkeeping(name, attribute)
+
+          type = attribute.type
+          next unless type.is_a?(Class) && type < Base
+
+          validate_attribute(name, attribute, type)
+        end
+      end
+
+      # `using_default_for` is public on lutaml, for its own deserializer
+      # to mark an attribute absent from the document. A caller can reach
+      # it too -- through the block form of `new`, before this runs -- and
+      # flip ANY attribute to "using its default" while it still holds
+      # the value it was actually given. Rendering skips whatever is
+      # marked default, so the value survives the reader and vanishes
+      # from the document -- measured on a required attribute (`to_json`
+      # rendered `{"message":"m"}` for an Issue whose `severity` still
+      # read back "info", and reloading that JSON raised
+      # `ValidationError: Missing required attribute: severity`) and
+      # separately on optional, unguarded ones (`source_path`, `format`,
+      # `Issue#code` all round-tripped to nil having read back their real
+      # value right up to the freeze).
+      #
+      # None of these models declares `default:`, so a genuine default is
+      # always blank -- nil for a scalar, empty for a collection, once
+      # `normalize` has run (which it has by here). A NON-blank value
+      # under a true `using_default?` is therefore always the bookkeeping
+      # lying about a value that IS present, never a legitimate default,
+      # whether or not the attribute is required.
+      def validate_default_bookkeeping(name, attribute)
+        return unless using_default?(name)
+
+        value = public_send(name)
+        blank = attribute.collection? ? value.empty? : value.nil?
+        return if blank
+
+        refuse(name, "recorded as explicitly set", "flagged as using its default")
+      end
+
+      # JSON has neither Infinity nor NaN. lutaml coerces both without
+      # complaint -- measured: `{"width":1e400}` deserialized to
+      # Float::INFINITY, the lifecycle froze the model around it, and the
+      # `to_json` that followed raised `JSON::GeneratorError`, so a
+      # document that parsed could not be written back out. Refused here,
+      # where the attribute name is still in hand.
+      def validate_finite(name)
+        value = public_send(name)
+        return unless value.is_a?(Numeric) && !value.finite?
+
+        refuse(name, "a finite number", value)
+      end
+
+      # Lutaml's generated getter consults a scalar enum's backing Array
+      # before `validate_types`. Own a core copy first so virtual `first`
+      # cannot show validation a different value from the one later
+      # frozen and rendered.
+      def own_enum_storage(name, attribute, raw)
+        return raw if attribute.collection? || !attribute.enum?
+        return raw if core_instance?(raw, ::NilClass) ||
+                      Lutaml::Model::Utils.uninitialized?(raw)
+
+        refuse(name, "a core Array", class_of(raw)) unless core_instance?(raw, ::Array)
+
+        copy = []
+        each_array(raw) { |value| copy << own_enum_value(name, attribute, value) }
+        object_frozen?(self) ? raw : copy
+      end
+
+      def own_enum_value(name, attribute, value)
+        return value if Lutaml::Model::Utils.uninitialized?(value)
+        return value unless attribute.type == Lutaml::Model::Type::String
+
+        refuse(name, "a String enum value", class_of(value)) unless inherits_from?(value, ::String)
+        own_string(name, value)
+      end
+
+      # No `unless value.is_a?(Array)` guard here any more: lutaml-model
+      # 0.8.32 (lutaml/lutaml-model#185) auto-wraps ANY non-Array value
+      # handed to a `collection: true` attribute into a one-element Array
+      # before this runs, at both construction and deserialization --
+      # `Report.new(issues: some_issue)` and
+      # `Report.from_json({"issues":{...}})` both now read back
+      # `issues == [some_issue]`. The shape check can no longer fire; only
+      # the per-element type check below still can, unchanged.
+      def validate_attribute(name, attribute, type)
+        value = public_send(name)
+        return validate_type(name, type, value, nullable: true) unless attribute.collection?
+
+        value.each { |element| validate_type(name, type, element, nullable: false) }
+      end
+
+      # A singular model attribute may be absent; a collection member may
+      # not -- a nil there reaches recursion and dies as a NoMethodError.
+      def validate_type(name, type, element, nullable:)
+        return if nullable && element.nil?
+        return if element.is_a?(type)
+
+        refuse(name, type, element.class)
+      end
+    end
+
+    # lutaml-model 0.8.19 validates nothing on its own: a bogus enum
+    # constructs and serializes, a missing attribute becomes nil, and
+    # `validate!` does not reach nested models. Every model therefore runs
+    # one lifecycle -- normalize, validate, freeze -- at both doors.
+    class Base < Lutaml::Model::Serializable
+      include Validation
+
+      DESERIALIZING = :claricle_models_deserializing
+      # Lutaml builds every model -- parent and nested alike -- by calling
+      # `new` with exactly this and populating it afterwards. Direct
+      # construction always carries real attributes.
+      BLANK_CONSTRUCTION = [:lutaml_register].freeze
+      private_constant :DESERIALIZING, :BLANK_CONSTRUCTION
+
+      # Public on lutaml, for its own XML allocation path
+      # (`allocate_for_deserialization`, reached only through an `xml`
+      # mapping block) to reset every attribute to a shared empty-
+      # collection sentinel or `UninitializedClass.instance` before
+      # filling it in field by field. None of these models declares an
+      # `xml` block, so lutaml never calls either method on one -- but a
+      # caller reached them too, through the block form of `new`, before
+      # this runs. Measured: `init_deserialization_state(:default)` wiped
+      # a Report's `source_path` to the sentinel and its whole `issues`
+      # collection to `[]`, and the model sealed reporting `valid: :yes`
+      # over an issue the caller had actually supplied -- no schema
+      # violation to catch, since the wiped shape is indistinguishable
+      # from a Report the caller genuinely built empty. Hidden rather
+      # than checked for, because the collection wipe leaves no value
+      # anywhere in the object for `validate_types` to catch.
+      private :init_deserialization_state, :finalize_deserialization
+
+      # Deserialization builds a blank instance and populates it afterwards,
+      # so `initialize` must not finalize during that window. Neither the
+      # key nor the value is secret; the protection is that BOTH the extent
+      # and lutaml's blank signature must hold, so ordinary construction
+      # validates however the thread-local was set. Forging both yields an
+      # empty model, which `allocate` already gives anyone who wants one.
+      # `Thread.current[]` is fiber-local, so a boundary it does not cross
+      # makes construction validate rather than skip.
+      #
+      # `of` rather than `from`: every `from_*` parses and then delegates
+      # here, so this one override also covers `of_json` and friends. A
+      # top-level array arrives already finalized, because `of` maps it back
+      # through itself one item at a time.
+      def self.of(format, doc, options = {})
+        outer = Thread.current[DESERIALIZING]
+        Thread.current[DESERIALIZING] = true
+        begin
+          result = super
+        ensure
+          Thread.current[DESERIALIZING] = outer
+        end
+        result.is_a?(Array) ? result : result.finalize
+      end
+
+      # Lutaml normally deletes bytes it cannot transcode before assigning
+      # them. Preserve those bytes so the name-aware lifecycle below can
+      # report why the declared String is unusable instead of calling a
+      # required value missing.
+      def self.ensure_utf8(value)
+        return super unless value.is_a?(::String) && !Lutaml::Model.opal?
+
+        value.encode(Encoding::UTF_8)
+      rescue EncodingError
+        value
+      end
+
+      # Lutaml also accepts a positional attributes Hash, so take whatever
+      # the superclass takes.
+      # Both conditions are required. Inside a deserialization but with
+      # real attributes means a caller built this themselves -- through a
+      # coercion callback, say -- so it validates now. Outside one, the
+      # thread-local is meaningless however it was set.
+      def initialize(*args, **kwargs)
+        super
+        finalize unless args.empty? &&
+                        kwargs.keys == BLANK_CONSTRUCTION &&
+                        Thread.current[DESERIALIZING]
+      end
+
+      def initialize_copy(other)
+        super
+        @claricle_sealed = false
+        finalize
+      end
+
+      def finalize
+        validate_deeply
+        seal
+        self
+      end
+
+      def validate_deeply
+        clear_uninitialized
+        normalize
+        validate!
+        validate_types
+        nested_models.each(&:validate_deeply)
+      end
+
+      protected
+
+      # Idempotent on our own bookkeeping rather than on `frozen?`, so a
+      # model frozen by other code is not mistaken for a sealed one. An
+      # empty model with a required attribute never reaches here --
+      # validation rejects it first; Report and Location have none, so an
+      # empty instance of either is valid and does reach this point. A
+      # populated one that dies does so partway through, which is the
+      # externally-frozen case tested below.
+      #
+      # The marker goes on last, beside the freeze it stands for. Set
+      # first, a child that refused to seal left the parent marked sealed
+      # and still mutable, and every later `seal` returned at the guard --
+      # measured: the block form of `new` handed back a Report that called
+      # itself sealed, took another issue, and changed its own verdict.
+      # There is no cycle for an early marker to break: nesting runs
+      # Report -> Issue -> Location and stops.
+      #
+      # Protected, not public: it freezes without revalidating, so a
+      # caller holding a model that failed to finalize (the block form of
+      # `new` hands one over before the exception) could mutate it into
+      # any shape and freeze it straight past `validate_deeply` -- measured,
+      # a poisoned Issue sealed with `severity: "bogus"` and serialized.
+      # `finalize` is the only public door, and it always validates first.
+      # Explicit block form for the recursive call below: `Symbol#to_proc`
+      # calls `public_send`, which a protected method refuses.
+      def seal
+        return self if @claricle_sealed
+
+        # rubocop:disable Style/SymbolProc -- &:seal calls public_send,
+        # which a protected method refuses; the block calls it directly.
+        nested_models.each { |model| model.seal }
+        # rubocop:enable Style/SymbolProc
+        freeze_attributes
+        # Lutaml tracks which attributes still hold defaults in a mutable
+        # hash, and `using_default_for` is public. Flipping an entry on a
+        # frozen model drops that attribute from the document -- measured:
+        # marking every one of an issue's fields turns "issues":[...] into
+        # "issues":null, and a warning report then reloads valid. Freezing
+        # it here, after the attribute pass, leaves composition intact.
+        instance_variable_get(:@using_default)&.freeze
+        @claricle_sealed = true
+        freeze
+      end
+
+      private
+
+      # lutaml has a sentinel object standing for "never set", and the
+      # block form of `new` is the one door that can put it in a SINGULAR
+      # attribute's ivar. Through the five others -- keyword, positional,
+      # `from_hash`, `from_json`, and nested inside a parent -- lutaml
+      # erases it before our lifecycle runs and the ivar holds a plain
+      # nil. That is why the doors are made to agree by normalising
+      # rather than by refusing: a refusal is only reachable from one of
+      # the six.
+      #
+      # Measured on 0.8.19, the block form disagreed with the rest and
+      # with itself. `Location.new { |l| l.byte_offset(sentinel) }` raised
+      # `ValidationError: byte_offset expects a non-negative integer, got
+      # uninitialized`, while `Location.new { |l| l.chunk(sentinel) }`
+      # sealed and handed the sentinel itself back out of `chunk`, where
+      # a caller expects a String or nil. Worse on a required attribute:
+      # `Issue.new(severity: "error") { |i| i.message(sentinel) }` sealed
+      # and rendered `{"severity":"error"}`, a document missing a field
+      # it cannot be missing, which reloaded as `Missing required
+      # attribute: message`. Cleared to nil, the required check sees it.
+      #
+      # A COLLECTION never reaches here: lutaml wraps whatever the setter
+      # is given, so the ivar holds `[sentinel]` rather than the sentinel
+      # and `uninitialized?` is false. `validate_types` refuses that on
+      # its own -- measured, `issues expects Claricle::Models::Issue, got
+      # Lutaml::Model::UninitializedClass` -- which is the right answer
+      # for a member of a typed collection and not this method's job.
+      #
+      # A no-op on every other path. Measured across 16 shapes -- all
+      # four models, empty and fully populated, through `new`,
+      # `from_json`, `from_yaml`, `from_hash`, `of_json`, `dup` and
+      # nested inside a parent -- it cleared nothing in any of them.
+      def clear_uninitialized
+        self.class.attributes.each do |name, attribute|
+          slot = :"@#{name}"
+          original = instance_variable_get(slot)
+          raw = own_enum_storage(name, attribute, original)
+          instance_variable_set(slot, raw) unless raw.equal?(original)
+          next unless Lutaml::Model::Utils.uninitialized?(stored_value(raw, attribute))
+
+          instance_variable_set(slot, nil)
+        end
+      end
+
+      # lutaml wraps a singular enum's value in an Array, so its sentinel
+      # arrives as `[sentinel]` and identity against the singleton walks
+      # straight past it. The same wrapper `own_enum_storage` reads
+      # through, and the same guard it uses to find it.
+      #
+      # Measured before this looked inside: `Inspection.new { |x|
+      # x.parse_status = sentinel }` sealed and rendered `{"issues":[]}`
+      # -- a required attribute absent from the document -- and reloading
+      # that raised `Missing required attribute: parse_status`. Every
+      # other door refused it outright. `Issue#severity` did the same.
+      #
+      # A collection's `[sentinel]` is deliberately left alone: there the
+      # Array is the value, not a wrapper, and `validate_types` refuses
+      # the member on its own.
+      def stored_value(raw, attribute)
+        return raw if attribute.collection? || !attribute.enum?
+        return raw unless core_instance?(raw, ::Array) && array_size(raw) == 1
+
+        array_first(raw)
+      end
+
+      # Refused, rather than supported. Ruby's default Marshal writes the
+      # ivars into a fresh object and runs neither the constructor nor the
+      # lifecycle -- measured: the copy came back unfrozen, took
+      # `severity = "bogus"` past the enum, and rendered it. Nothing in
+      # this gem forks, caches or crosses a process boundary, so no model
+      # is dumped at all rather than dumped through a protocol of its own.
+      # A real one can be written the day something actually needs it.
+      #
+      # This closes the dump side only, and does not pretend otherwise.
+      # `Marshal.load` of bytes a caller got from somewhere else still
+      # builds whatever those bytes describe -- measured, a hand-built
+      # ordinary-object payload naming this class loaded unfrozen with
+      # `severity: "bogus"`. That was equally true before this refusal
+      # existed: `_load` was only ever reached for payloads our own
+      # `_dump` had written, never for a payload someone else shaped.
+      # Nothing in this gem calls `Marshal.load`.
+      #
+      # `_dump` and not `marshal_dump`: Ruby prefers `marshal_dump` where
+      # both exist, so the refusal sits on the hook a later `marshal_dump`
+      # would have to displace deliberately. Private, because Marshal
+      # reaches a private `_dump` on the class and on every subclass --
+      # measured -- so nothing is gained by publishing it. It covers a
+      # model nested inside a plain Hash or Array too, also measured.
+      def _dump(_depth)
+        raise TypeError, "cannot marshal #{self.class}: Claricle models are not marshalable"
+      end
+
+      # Freeze declared attributes only, and freeze them where they lie.
+      # Inspection owns and freezes its free-form Hash before this pass.
+      # Works on the backing storage, not the getters. An enum declared with
+      # `values:` is stored as a mutable Array behind a String getter, so
+      # freezing what the getter returns leaves that array writable and a
+      # frozen report can still have its verdict changed. Writing the ivar
+      # rather than calling the setter also leaves lutaml's `using_default`
+      # bookkeeping alone.
+      #
+      # Strings are duplicated first: `new` hands us its own copy, but
+      # `from_hash` aliases the caller's, and freezing that would take their
+      # String away from them.
+      def freeze_attributes
+        self.class.attributes.each_key do |name|
+          slot = :"@#{name}"
+          raw = instance_variable_get(slot)
+          if inherits_from?(raw, ::String)
+            instance_variable_set(slot, own_string(name, raw))
+          elsif core_instance?(raw, ::Array)
+            instance_variable_set(slot, own_array(name, raw))
+          end
+        end
+      end
+
+      def own_array(name, value)
+        copy = []
+        each_array(value) { |element| copy << own_string(name, element) }
+        copy.freeze
+      end
+
+      def own_string(name, value)
+        return value unless inherits_from?(value, ::String)
+
+        copy = ::String.new(value)
+        JSON.generate(copy)
+        copy.freeze
+      rescue JSON::GeneratorError => e
+        refuse(name, "a String JSON can render", e.message)
+      end
+
+      def normalize; end
+
+      def nested_models
+        []
+      end
+    end
+
+    # Validation is an implementation detail of Base, not an extension
+    # point -- Base is private, so a mixin only Base uses has no caller
+    # left to serve.
+    private_constant :Base, :Validation
+  end
+end

data/lib/claricle/models/batch_item.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "report"
+require_relative "conversion"
+require_relative "uncoerced_integer"
+
+module Claricle
+  module Models
+    # Why this is not a Models::Issue: an Issue is the document's problem,
+    # and this is the operation's. A file that could not be opened, or whose
+    # format nothing handles, has no conformance verdict at all -- collapsing
+    # the two would blur the one line the envelope exists to draw.
+    class BatchError < Base
+      attribute :code, :string, required: true
+      attribute :message, :string, required: true
+    end
+
+    # One slot of a batch, and the only element type a batch ever holds. A
+    # heterogeneous array of results and failures would force a consumer to
+    # type-switch on whether a field is present, and `jq '.[].result.valid'`
+    # would answer null for an operational failure -- indistinguishable from
+    # a genuine null.
+    class BatchItem < Base
+      # The codes a process status can carry, so this cannot record one the
+      # shell would misread. The same range Cli::Runner::Status enforces.
+      CODES = (0..255)
+      private_constant :CODES
+
+      attribute :path, :string, required: true
+      # Recomputed in `normalize` from the two fields below, so whatever a
+      # caller or a document supplies here is overwritten before the model
+      # seals. Three values, not two: "the operation ran and said no" and
+      # "the operation could not run" are different answers, and the second
+      # is why an operational failure must never read as a verdict.
+      #
+      # Report#valid derives the same kind of summary through a `with:`
+      # mapping instead. That route is closed here: lutaml 0.8.22 invokes a
+      # `with:` mapping's `from` method on a throwaway instance built by
+      # `mapper_class.new` with no arguments at all
+      # (mapping_rule.rb:412-417), and Base's lifecycle validates that
+      # instance -- measured, `BatchItem.new` raises ValidationError on the
+      # two required attributes above. Report has no required attribute, so
+      # it never met this. A `to`-only mapping is refused outright
+      # ("`:with` argument for mapping 'status' requires :to and :from").
+      attribute :status, :string, values: %w[ok failed error]
+      attribute :exit_code, UncoercedInteger, required: true
+      # A union rather than a plain `Report`, now that a batch can also hold
+      # a conversion. Lutaml resolves which member a Hash/JSON value is by
+      # key coverage (`Union.conform_model`, lutaml-model union.rb:163-180):
+      # every input key must belong to the member's mapped fields. Report and
+      # Conversion both map "source_path", but are disjoint on every OTHER
+      # field -- Report also maps "format"/"issues"/"valid", Conversion also
+      # maps "source_format"/"target_format"/"lossiness"/"output_path" -- so
+      # a real document built by either one always carries at least one of
+      # those and resolves unambiguously. Only a Hash bearing "source_path"
+      # and nothing else would be genuinely ambiguous, and nothing in this
+      # codebase builds one. Declared order does not matter for any real
+      # input; Report is listed first as it is the existing, more common
+      # case.
+      #
+      attribute :result, [Report, Conversion]
+      alias cast_result= result=
+      private :cast_result=
+
+      # Lutaml casts a value matching neither union member to nil. Refuse it
+      # here while the caller's original value is still available.
+      def result=(value)
+        self.cast_result = value
+        validate_result(value)
+        value
+      end
+
+      attribute :error, BatchError
+
+      # Keyword and positional-hash construction cast union values before
+      # calling the writer, so retain the original until casting finishes.
+      def initialize(*args, **kwargs)
+        supplied_result = result_argument(args, kwargs)
+        super
+        validate_result(supplied_result)
+      end
+
+      private
+
+      def result_argument(args, kwargs)
+        return kwargs[:result] if kwargs.key?(:result)
+
+        attributes = args.first
+        attributes[:result] if attributes.is_a?(::Hash) && attributes.key?(:result)
+      end
+
+      def validate_result(value)
+        return if value.nil? || result.is_a?(Report) || result.is_a?(Conversion)
+
+        refuse(:result, "a Report or Conversion", value.class)
+      end
+
+      # The verdict is written here rather than read from what arrived, so a
+      # document cannot assert a status its own fields contradict, and the
+      # stored value cannot drift from them.
+      def normalize
+        self.status = derived_status
+      end
+
+      def derived_status
+        return "error" if error
+        return "ok" if exit_code.is_a?(::Integer) && exit_code.zero?
+
+        "failed"
+      end
+
+      # The declared type keeps the caller's value intact precisely so this
+      # can tell `"3"` from the `3` lutaml would have made of it.
+      def validate_types
+        super
+        return if exit_code.is_a?(::Integer) && CODES.cover?(exit_code)
+
+        refuse(:exit_code, "an Integer in #{CODES}", exit_code.inspect)
+      end
+
+      def nested_models
+        [result, error].compact
+      end
+    end
+  end
+end