claricle 0.1.0 → 0.2.0

data/lib/claricle/emf_header.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Claricle
+  # emfsvg's writer leaves EMR_HEADER.nBytes (u32 at offset 48) at 0, so
+  # its output declares a size the file does not have. `seal` writes the
+  # real length; bytes that are not an EMF header, or that already declare
+  # a size, pass through untouched, as does any target other than :emf.
+  # nRecords and nHandles are written correctly by the delegate and are
+  # not touched.
+  module EmfHeader
+    HEADER_TYPE = 1
+    N_BYTES_OFFSET = 48
+    MIN_HEADER_BYTES = 52
+
+    module_function
+
+    def seal(target, bytes)
+      return bytes unless target == :emf && unsealed?(bytes)
+
+      sealed = bytes.b
+      sealed[N_BYTES_OFFSET, 4] = [sealed.bytesize].pack("V")
+      sealed
+    end
+
+    def unsealed?(bytes)
+      bytes.bytesize >= MIN_HEADER_BYTES &&
+        bytes.byteslice(0, 4).unpack1("V") == HEADER_TYPE &&
+        bytes.byteslice(N_BYTES_OFFSET, 4).unpack1("V").zero?
+    end
+  end
+
+  private_constant :EmfHeader
+end

data/lib/claricle/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Claricle
+  class Error < StandardError; end
+
+  class UnknownFormat < Error; end
+
+  # Bad arguments, conflicting flags, a refused destination. Besides
+  # Thor::Error and ENOENT, the only *mapped error class* that means exit
+  # 2 -- a command can still request 2 explicitly with a Status, or by
+  # exiting, since Runner hands a SystemExit's own status back when it is
+  # a valid byte.
+  class InvocationError < Error; end
+
+  # A conversion that failed after dispatch. Reaches exit 4 through the
+  # ordinary StandardError row; there is no blanket Claricle::Error row.
+  class ConversionError < Error; end
+
+  # Raised when a profile is recognised as a name some format defines, but
+  # not by the format of the file in hand. Separate from UnsupportedFormat
+  # because the format IS supported -- it is the pairing that is wrong,
+  # and a caller fixes the two by different means. Names what the format
+  # does accept, because a refusal that does not is a second question.
+  class UnsupportedProfile < InvocationError
+    def initialize(format, profile, accepted)
+      super(build_message(format, profile, accepted))
+    end
+
+    private
+
+    def build_message(format, profile, accepted)
+      message = "format #{format.inspect} does not define profile #{profile.to_s.inspect}"
+      return "#{message}; it defines none" if accepted.empty?
+
+      "#{message}; it defines #{accepted.map(&:inspect).join(", ")}"
+    end
+  end
+
+  # Raised when a format is recognised but nothing handles it, or handles
+  # the operation asked for. The class builds its own sentence: callers
+  # pass what they were doing, not a phrase.
+  class UnsupportedFormat < Error
+    # A target nobody can pass, so "not given" and "given as nil" stay
+    # different things. `convert(image, to:)` requires the keyword, so a
+    # nil arriving here is a caller who forgot their target, not one who
+    # has none, and the message says so.
+    ABSENT = Object.new.freeze
+    private_constant :ABSENT
+
+    def initialize(format, operation = nil, target: ABSENT)
+      super(build_message(format, operation, target))
+    end
+
+    private
+
+    # No readers and no state: the arguments exist to compose one sentence.
+    # A target without an operation reads as nonsense, so it is ignored
+    # rather than rendered.
+    #
+    # Every supplied target is named, however unhelpful it looks. Tested
+    # by truthiness the message dropped `false`; tested for nil it
+    # dropped `nil`. Both had been supplied, and both times the error
+    # named the operation and hid what it was refused for.
+    def build_message(format, operation, target)
+      message = "format #{format.inspect} is not supported"
+      return message unless operation
+
+      message << " for #{operation}"
+      message << " to #{target.inspect}" unless target.equal?(ABSENT)
+      message
+    end
+  end
+end

data/lib/claricle/fault.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Claricle
+  # An exception described as data: the status it means, and a message that
+  # can be rendered. Both are needed in two places -- the CLI runner turns a
+  # fault into a process status, and a batch turns one into an envelope --
+  # and a second copy of either rule is a second place for them to disagree.
+  #
+  # Thor's own errors are deliberately absent. They are the CLI's business,
+  # they cannot reach a batch operation, and naming them here would drag
+  # `require "thor"` into the library layer.
+  module Fault
+    CLASS_OF = ::Object.instance_method(:class)
+    KIND_OF = ::Object.instance_method(:is_a?)
+    MODULE_NAME = ::Module.instance_method(:name)
+    MODULE_TO_S = ::Module.instance_method(:to_s)
+    private_constant :CLASS_OF, :KIND_OF, :MODULE_NAME, :MODULE_TO_S
+
+    module_function
+
+    def exit_code(error)
+      case error
+      when Errno::ENOENT, InvocationError then 2
+      when UnknownFormat, UnsupportedFormat then 3
+      else 4
+      end
+    end
+
+    # A delegate's message is not guaranteed to be valid UTF-8. Left alone
+    # it reaches a String attribute that Models::Base refuses because JSON
+    # cannot render it, so reporting the failure would become the failure.
+    def message(error)
+      value = raw_message(error)
+      value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue EncodingError
+      value.b.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    end
+
+    # Call the core readers directly. An exception is an ordinary Ruby
+    # object and can override #class just as it can override #message; the
+    # diagnostic path must still name the exception that was actually raised.
+    def class_name(error)
+      klass = CLASS_OF.bind_call(error)
+      MODULE_NAME.bind_call(klass) || MODULE_TO_S.bind_call(klass)
+    end
+
+    def matches_class?(error, kind)
+      KIND_OF.bind_call(error, kind)
+    end
+
+    # Exception subclasses can override #message, including with a non-String
+    # result or another exception. Reporting must not replace the original
+    # failure with a failure from its diagnostic path. Copy a real String into
+    # the core class so an overridden #encode cannot do the same thing later.
+    def raw_message(error)
+      value = error.message
+      return ::String.new(value) if ::String === value # rubocop:disable Style/CaseEquality
+
+      class_name(error)
+    rescue StandardError
+      class_name(error)
+    end
+    private_class_method :raw_message
+  end
+
+  private_constant :Fault
+end

data/lib/claricle/handlers/base.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../models/inspection"
+require_relative "../models/issue"
+require_relative "extension_points"
+
+module Claricle
+  module Handlers
+    # A handler declares the formats it owns and implements the operations
+    # it supports. Anything it does not implement raises, naming what was
+    # asked for, so an unfinished handler says so rather than returning nil.
+    class Base
+      include ExtensionPoints
+
+      # Each operation, mapped to the method a handler overrides to
+      # support it. The names are the vocabulary of the public API; the
+      # CLI happens to print them, but does not own them.
+      OPERATIONS = {
+        inspect: :inspection,
+        conform: :conformance_report,
+        convert: :convert
+      }.freeze
+      private_constant :OPERATIONS
+
+      class << self
+        # One declaration per handler, refused on a second call. The
+        # registry derives a frozen map at load, so a later redeclaration
+        # would leave the two disagreeing about who owns a format --
+        # measured: after `Png.formats(:svg)` the registry still answered
+        # :png while the handler claimed :svg.
+        #
+        # What this refuses is a change of mind, not a late first
+        # declaration. A class that has declared nothing by the time
+        # registry.rb reads the list owns nothing in the map, and
+        # declaring afterwards leaves it claiming a format the registry
+        # does not route. No handler does that -- the declaration sits in
+        # the class body, which has run before the list is read -- so the
+        # guarantee here is "no take-backs", not "the two can never
+        # disagree".
+        def formats(*symbols)
+          raise Error, "#{self} already declared formats #{@formats.inspect}" if @formats
+
+          # Symbols only. The registry keys its map on these and sorts the
+          # keys for `Registry.formats`, so one String among them is not a
+          # near miss -- measured: after `formats "png", :svg` the sort
+          # raises `comparison of String with :svg failed`, and
+          # `handler_for(:png)` calls :png unsupported. Refused where the
+          # typo is rather than at the first call that trips over it.
+          bad = symbols.grep_v(Symbol)
+          raise Error, "#{self} declared non-Symbol formats #{bad.inspect}" if bad.any?
+
+          @formats = symbols.freeze
+        end
+
+        def supported_formats
+          @formats || [].freeze
+        end
+
+        # The profile names this handler's conform operation accepts, in
+        # the order the format's own spec ranks them, so the FIRST is what
+        # a plain `conform` runs. Declared rather than derived, unlike
+        # `capabilities` below: a profile is a name in a delegate's own
+        # vocabulary, and nothing in the handler's method list says which
+        # names those are.
+        #
+        # Refused twice over on the same grounds as `formats` -- no
+        # take-backs, and Symbols only, because `Registry.profiles_for`
+        # sorts these and one String among them raises on comparison
+        # rather than at the typo.
+        def profiles(*symbols)
+          raise Error, "#{self} already declared profiles #{@profiles.inspect}" if @profiles
+
+          bad = symbols.grep_v(Symbol)
+          raise Error, "#{self} declared non-Symbol profiles #{bad.inspect}" if bad.any?
+
+          @profiles = symbols.freeze
+        end
+
+        # Empty means "this format has no profiles", which is a real
+        # answer and not a gap: PNG conformance is one fixed requirement
+        # set, so there is nothing to choose between.
+        def supported_profiles
+          @profiles || [].freeze
+        end
+
+        # nil means this profile takes no separate level. Handlers with
+        # level-bearing profiles override this with their accepted names.
+        def levels_for(_profile)
+          nil
+        end
+
+        # A handler's convert target list, declared the same way `formats`
+        # is and for the same reason: two calls would let a handler change
+        # its mind about what it converts to, and the registry would have
+        # no way to notice. Kept as its own declaration rather than derived
+        # from overriding `convert` -- a handler can convert to several
+        # targets through one method, and `capabilities` already answers
+        # the yes/no question from whether `convert` is overridden at all.
+        def convert_to(*symbols)
+          raise Error, "#{self} already declared convert targets #{@convert_targets.inspect}" if @convert_targets
+
+          bad = symbols.grep_v(Symbol)
+          raise Error, "#{self} declared non-Symbol convert targets #{bad.inspect}" if bad.any?
+
+          @convert_targets = symbols.freeze
+        end
+
+        def convert_targets
+          @convert_targets || [].freeze
+        end
+
+        # Derived, never declared. A declaration is a second place to say
+        # what the code already says, and it can advertise an operation
+        # that is still Base's raising stub -- exactly the lie `formats`
+        # exists to avoid. Overriding the method is the only way to claim
+        # the capability. Item 04's conversion targets stay declared,
+        # because a list of targets is data rather than a boolean.
+        def capabilities
+          OPERATIONS.reject { |_, method| instance_method(method).owner == Base }.keys
+        end
+      end
+
+      # The image's own format, not the first one this handler declares --
+      # a handler owning :svg and :svgz would otherwise name :svg however
+      # it was reached. The operation named is the user-facing one, so
+      # `inspection` reports `inspect` (D2 renamed the method because Ruby
+      # owns `inspect`, but the command is still `inspect`).
+      def inspection(image)
+        raise UnsupportedFormat.new(image.format, :inspect)
+      end
+
+      def conformance_report(image)
+        raise UnsupportedFormat.new(image.format, :conform)
+      end
+
+      def convert(image, to:)
+        raise UnsupportedFormat.new(image.format, :convert, target: to)
+      end
+
+      private
+
+      # The one shape every handler needs and none of them differ on: a
+      # parse that did not get far enough to report anything, carrying the
+      # single error that says why. Severity is not a parameter because
+      # there is only one answer -- an inspection that failed to parse has
+      # nothing to warn about.
+      #
+      # The image's own format, for the same reason `inspection` names it:
+      # a handler owning :svg and :svgz must not report :svg for both.
+      #
+      # `parse_status: "failed"` makes no validity claim; that belongs to
+      # conform alone (D17).
+      def failed_inspection(image, code:, message:)
+        Models::Inspection.new(
+          format: image.format.to_s,
+          parse_status: "failed",
+          issues: [Models::Issue.new(severity: "error", code: code, message: message)]
+        )
+      end
+    end
+
+    private_constant :Base
+  end
+
+  # Private where it is defined, so the guarantee survives this file
+  # being required on its own rather than through the entry point.
+  private_constant :Handlers
+end

data/lib/claricle/handlers/extension_points.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../lossiness"
+require_relative "../models/conversion"
+
+module Claricle
+  module Handlers
+    # What a handler declares so that adding its format is that one class and
+    # no edit elsewhere: how the format is recognised, what it can be
+    # converted from, and what that conversion loses. Included by Base.
+    module ExtensionPoints
+      # Bounds the READ of a source being converted INTO a handler's format,
+      # the same limit every outbound converter applies.
+      MAX_CONVERT_BYTES = 200 * 1024 * 1024
+      private_constant :MAX_CONVERT_BYTES
+
+      def self.included(base) = base.extend(ClassMethods)
+
+      module ClassMethods
+        # How this format is recognised: a block handed the first bytes of
+        # the input (a binary String, at most `Detector::HEADER_BYTES`),
+        # answering one of this handler's own formats as a Symbol, or nil.
+        # The built-in probes run first and this runs only for input none
+        # of them claimed, so a new format cannot change what an existing
+        # one detects. A Symbol outside `formats` is a defect in the
+        # handler and raises where it happens, not later as a routing miss.
+        def detect(&probe)
+          raise ArgumentError, "detect needs a block" unless probe
+          raise Error, "#{self} already declared a detector" if @detector
+
+          @detector = probe
+        end
+
+        def detect_format(header)
+          format = @detector&.call(header)
+          return format if format.nil? || supported_formats.include?(format)
+
+          raise Error, "#{self} detected #{format.inspect}, which it did not declare in formats"
+        end
+
+        # Declares that this handler can PRODUCE its formats from the given
+        # source formats. The block receives the source bytes and the
+        # target format and returns the converted bytes. Declared on the
+        # target's handler, so adding a format never edits the source's.
+        # A source handler that already lists the target in `convert_to`
+        # keeps its own path.
+        def convert_from(*sources, &producer)
+          raise ArgumentError, "convert_from needs a block" unless producer
+
+          bad = sources.grep_v(Symbol)
+          raise Error, "#{self} declared non-Symbol convert sources #{bad.inspect}" if bad.any?
+
+          sources.each do |source|
+            raise Error, "#{self} already declared a converter from #{source.inspect}" if converters.key?(source)
+
+            converters[source] = producer
+          end
+        end
+
+        def converters
+          @converters ||= {}
+        end
+
+        def convert_sources
+          converters.keys
+        end
+
+        # The SVG features converting INTO this format loses and keeps, in
+        # the vocabulary of `Lossiness`. Optional: without it a conversion
+        # into this format is reported `unknown`, never `lossless`.
+        def loss_rules(lost:, kept:)
+          raise Error, "#{self} already declared loss rules" if @loss_rule
+
+          @loss_rule = { lost: lost.freeze, kept: kept.freeze }.freeze
+        end
+
+        attr_reader :loss_rule
+      end
+
+      # Converts `image` INTO one of this handler's formats, through the
+      # producer declared with `convert_from` for the image's format.
+      # Reached from `Image#convert` only when the source's own handler
+      # does not list the target.
+      def convert_inbound(image, to:)
+        producer = self.class.converters.fetch(image.format) do
+          raise UnsupportedFormat.new(image.format, :convert, target: to)
+        end
+        content = bounded_content(image)
+        conversion(image, to, content, produce(producer, content, to))
+      end
+
+      private
+
+      def conversion(image, to, content, converted)
+        loss = Lossiness.classify(source_format: image.format, target_format: to,
+                                  source: content, rule: self.class.loss_rule)
+        Models::Conversion.new(source_path: image.path, source_format: image.format.to_s,
+                               target_format: to.to_s, lossiness: loss, content: converted)
+      end
+
+      def bounded_content(image)
+        content = image.with_source { |source| bounded_read(source) }
+        return content if content.bytesize <= MAX_CONVERT_BYTES
+
+        raise ConversionError, "#{image.format} image exceeds the #{MAX_CONVERT_BYTES}-byte convert limit"
+      end
+
+      def bounded_read(source)
+        return source.read(MAX_CONVERT_BYTES + 1) || "".b if source.respond_to?(:read)
+
+        source.byteslice(0, MAX_CONVERT_BYTES + 1)
+      end
+
+      # Scoped to the producer alone: what the producer raises is not ours
+      # to enumerate, and the rest of `convert_inbound` is.
+      def produce(producer, content, to)
+        producer.call(content, to)
+      rescue StandardError => e
+        raise ConversionError, "#{e.class}: #{e.message}"
+      end
+    end
+  end
+end