claricle 0.1.0 → 0.2.0

data/lib/claricle/cli.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Claricle
   # Command-line interface for Claricle
   class Cli < Thor
@@ -7,61 +9,533 @@ module Claricle
       true
     end
 
+    # Thor >= 1.5 contributes both `help` and `tree` to every subclass.
+    # Claricle keeps `help` and drops `tree`. Guarded because the gemspec
+    # permits Thor down to 1.2, where `tree` does not exist and
+    # `undefine: true` on a missing method raises NameError.
+    remove_command :tree, undefine: true if method_defined?(:tree)
+
     desc "version", "Display Claricle version"
     def version
-      puts "Claricle version #{Claricle::VERSION}"
+      tolerate_closed_output { puts "Claricle version #{Claricle::VERSION}" }
+    end
+
+    # Thor supplies this command. The rescue is WIDE on purpose: it covers
+    # text generation as well as the write, so an `Errno::EPIPE` raised
+    # while Thor is still building the help page reports success too.
+    # Narrowing it to the write half needs Thor's shell calls buffered and
+    # replayed, and a replayed call cannot be given back the shell state it
+    # was made in -- see the gate record for the measured failure shapes.
+    # `spec/claricle/cli_help_spec.rb` pins the wide behaviour, so a future
+    # narrowing attempt is deliberate rather than accidental.
+    def help(command = nil, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
+      tolerate_closed_output { super(command, subcommand) }
+    end
+
+    desc "inspect FILE", "Report a file's format and metadata"
+    option :json, type: :boolean, default: false, desc: "Emit JSON"
+    # Named `inspect_file`, because a Thor command is an instance method
+    # and `def inspect(file)` would override `Object#inspect` on every
+    # Cli instance -- `p cli` then raises ArgumentError. This is D2's
+    # rule (`Image#inspect` became `#inspection`) applied one layer up.
+    # The command users type is still `inspect`; the re-key and the
+    # override below are what keep the method name from leaking out.
+    def inspect_file(file)
+      inspection = Image.from_path(file).inspection
+      payload = options[:json] ? inspection.to_json : Presenter.inspection(inspection)
+      tolerate_closed_output { puts payload }
+    end
+    # Thor registers a command under its METHOD name, so this shipped as
+    # the command `inspect_file` -- and `normalize_command_name`
+    # translates dashes to underscores, so `inspect-file` reached it too.
+    # `map "inspect" => :inspect_file` added a third spelling on top
+    # rather than replacing the first two.
+    #
+    # Re-keying the registry entry leaves exactly `inspect`. The Command
+    # object keeps its `inspect_file` name, so dispatch still reaches the
+    # method above and `Object#inspect` is never shadowed.
+    #
+    # The `map` alias is dropped rather than kept, because with the entry
+    # re-keyed `normalize_command_name("inspect")` would follow the alias
+    # back to the name that no longer exists.
+    commands["inspect"] = commands.delete("inspect_file")
+
+    # Thor prints a command's METHOD name in an arity error, and the
+    # method behind `inspect` is `inspect_file` -- so `claricle inspect`
+    # with no file answered `ERROR: "claricle inspect_file" was called
+    # with no arguments`, naming the one spelling this CLI rejects.
+    # Measured.
+    #
+    # The registry key is Thor's CANONICAL name for the command, which
+    # is not always what the user typed -- Thor resolves abbreviations
+    # first, so `claricle ins` arrives here with key `inspect`. That is
+    # the name worth printing either way. The message is built from a
+    # copy carrying it; a copy, because the original's name is what Thor
+    # dispatches on. A command whose key already matches is passed
+    # through untouched.
+    def self.handle_argument_error(command, error, args, arity)
+      key = commands.key(command)
+      command = command.dup.tap { |copy| copy.name = key } if key && key != command.name
+
+      super
+    end
+
+    desc "formats", "List the formats Claricle handles and what it can do with each"
+    option :json, type: :boolean, default: false, desc: "Emit JSON"
+    def formats
+      rows = Registry.formats.map { |format| Presenter.format_row(format) }
+      payload = options[:json] ? Models::FormatCapability.to_json(rows) : Presenter.format_table(rows)
+      tolerate_closed_output { puts payload }
+    end
+
+    desc "conform FILE...", "Check files against their format's conformance rules"
+    option :pattern, type: :string,
+                     desc: "Read this as a glob, whatever the filename looks like"
+    option :json, type: :boolean, default: false, desc: "Emit JSON"
+    option :strict, type: :boolean, default: false,
+                    desc: "Require a clean verdict, not merely the absence of errors"
+    option :profile, type: :string,
+                     desc: "Require conformance to a named profile the format defines"
+    option :level, type: :string, desc: "Select a level within a PDF profile"
+    def conform(*files)
+      result = Claricle.conformance_batch(*files, pattern: options[:pattern],
+                                                  strict: options[:strict],
+                                                  profile: options[:profile],
+                                                  level: options[:level])
+      # The status is settled before anything is written. `tolerate_closed_output`
+      # answers 0, which is right for a command that can only succeed and
+      # would silently turn a nonconformant batch into a passing one here.
+      tolerate_closed_output { write_conformance(result) }
+      Runner::Status.new(result.exit_code)
+    end
+
+    desc "convert SOURCE...", "Convert files to another format"
+    option :pattern, type: :string,
+                     desc: "Read this as a glob, whatever the filename looks like"
+    option :to, type: :string, desc: "Target format"
+    option :output, type: :string, desc: "Destination file, or - for stdout"
+    option :json, type: :boolean, default: false, desc: "Emit JSON"
+    option :force, type: :boolean, default: false, desc: "Overwrite an existing destination"
+    def convert(*files)
+      refuse_stdout_json_conflict
+      result = Claricle.convert_batch(*files, pattern: options[:pattern], to: options[:to],
+                                              output: options[:output], force: options[:force])
+      # Bytes for `--output -` are written to stdout as a side effect INSIDE
+      # `Claricle.convert_batch`, above -- unlike every other command, whose
+      # write happens afterward, guarded by `tolerate_closed_output` below.
+      # A closed consumer there is caught by Batch's own per-file rescue
+      # before it ever reaches this line, and reads as an ordinary
+      # conversion failure (exit 4) rather than the closed-pipe exit 0
+      # every sibling command gives. Restored explicitly here, since
+      # `tolerate_closed_output` cannot see a failure that already happened.
+      return Runner::Status.new(0) if closed_stdout_write?(result)
+
+      tolerate_closed_output { write_convert(result) }
+      Runner::Status.new(result.exit_code)
+    end
+
+    # Rendering, kept together so the commands only choose a payload and
+    # write it. Nothing here touches `options` or writes output.
+    module Presenter
+      # C0, DEL, C1, and Unicode's own two line breaks. Not just C0:
+      # U+0085 is NEL, a next-line control, and U+009B is CSI, the
+      # introducer an escape sequence uses -- both reachable as
+      # character references, both measured arriving in the output
+      # intact. U+2028 and U+2029 are line and paragraph separators by
+      # definition. Nothing here is a character a file has a reason to
+      # put in its metadata.
+      CONTROL = /[\u0000-\u001F\u007F-\u009F\u2028\u2029]/
+      # Named here rather than read off the model, so the printed order is
+      # chosen rather than whatever order the attributes happen to sit in.
+      LOCATION_FIELDS = %i[chunk byte_offset byte_length line column node_path].freeze
+      private_constant :CONTROL, :LOCATION_FIELDS
+
+      module_function
+
+      # Per file: the path, the tri-state verdict, and every mapped issue on
+      # one line. A conformant file prints its path and verdict, nothing
+      # more. A file whose operation could not run has no verdict to print
+      # and is reported on stderr instead.
+      def conformance(items)
+        items.reject { |item| item.status == "error" }
+             .flat_map { |item| ["#{visible(item.path)}: #{item.result.valid}", *issues(item)] }
+             .join("\n")
+      end
+
+      # Generic: a `BatchItem`'s failure shape (path + error message) is the
+      # same whatever operation produced it, so this is what `convert`'s own
+      # failure rendering calls too, rather than the conform-named method
+      # below or a near-duplicate of it.
+      def batch_failures(items)
+        items.select { |item| item.status == "error" }
+             .map { |item| "claricle: #{visible(item.path)}: #{visible(item.error.message)}" }
+      end
+
+      def conformance_failures(items)
+        batch_failures(items)
+      end
+
+      # Per file: the path, the target format, where the bytes landed
+      # ("-" for stdout, since `Writer#write` returns nil there), and the
+      # lossiness classification -- the line shape the plan card names.
+      # An errored item has no `Conversion` to describe and is reported
+      # on stderr instead, via `batch_failures`.
+      def conversions(items)
+        items.reject { |item| item.status == "error" }
+             .map { |item| conversion_line(item.path, item.result) }
+      end
+
+      # One stderr line per conversion whose lossiness is not `lossless`:
+      # the plan card requires disclosure, not consent.
+      def conversion_warnings(items)
+        items.reject { |item| item.status == "error" || item.result.lossiness == "lossless" }
+             .map { |item| conversion_warning(item.path, item.result) }
+      end
+
+      def conversion_warning(path, conversion)
+        verdict = conversion.lossiness == "lossy" ? "is lossy" : "has unknown lossiness"
+        "claricle: warning: #{visible(path)} -> #{conversion.target_format} #{verdict}"
+      end
+
+      def conversion_line(path, conversion)
+        written = conversion.output_path || "-"
+        "#{visible(path)} -> #{conversion.target_format}: #{visible(written)} (#{conversion.lossiness})"
+      end
+
+      def issues(item)
+        item.result.issues.map do |issue|
+          ["  #{visible(issue.severity)}", code(issue.code),
+           visible(issue.message), location(issue.location)].compact.join(" ")
+        end
+      end
+
+      # Absent, not `[]`: Issue#code is optional, and an empty bracket
+      # pair would read as a code nobody chose rather than one the
+      # delegate never reported.
+      def code(code)
+        return if code.nil?
+
+        "[#{visible(code)}]"
+      end
+
+      # Only what a delegate actually reported. Spelling out six fields
+      # would print four nils, and printing none would lose the ones that
+      # were measured.
+      def location(location)
+        return if location.nil?
+
+        populated = LOCATION_FIELDS.filter_map do |name|
+          value = location.public_send(name)
+          "#{name}: #{visible(value)}" unless value.nil?
+        end
+        "(#{populated.join(", ")})" unless populated.empty?
+      end
+
+      # Capabilities are derived from the handler, so this cannot
+      # advertise an operation that is still a raising stub.
+      def format_row(format)
+        capabilities = Registry.capabilities_for(format)
+
+        Models::FormatCapability.new(
+          format: format.to_s,
+          inspectable: capabilities.include?(:inspect),
+          conform: capabilities.include?(:conform),
+          convert: capabilities.include?(:convert),
+          convert_to: Registry.convert_targets_for(format).map(&:to_s)
+        )
+      end
+
+      def format_table(rows)
+        rows.map do |row|
+          operations = { inspect: row.inspectable, conform: row.conform, convert: row.convert }
+          "#{row.format}\t#{operations.select { |_, supported| supported }.keys.join(", ")}"
+        end.join("\n")
+      end
+
+      def inspection(inspection)
+        rows(inspection)
+          .filter_map { |label, value| "#{visible(label)}: #{visible(value)}" unless value.nil? }
+          .join("\n")
+      end
+
+      # Metadata is free text out of the file, and an SVG root attribute
+      # can hold a newline: `&#xA;` is a character reference, so XML
+      # keeps it as a real newline rather than folding it to a space.
+      # Printed raw, `id="a&#xA;error: forged"` produced an "error:"
+      # line of Claricle's own shape, and `&#xD;` overwrote the line in
+      # a terminal. Control characters are shown escaped instead.
+      #
+      # Only the human rendering needs this. `--json` carries the true
+      # value and JSON escapes it on the way out, so the two disagree on
+      # presentation and agree on the bytes.
+      def visible(text)
+        text.to_s.gsub(CONTROL) { |char| escaped(char.ord) }
+      end
+
+      # `\xNN` up to a byte, `\u{NNNN}` above it. One form for both
+      # would either print `\x2028` -- which reads as `\x20` followed by
+      # "28" -- or spell a newline `\u{000A}`.
+      def escaped(code)
+        code > 0xFF ? format("\\u{%04X}", code) : format("\\x%02X", code)
+      end
+
+      # Label/value pairs filtered once, rather than a conditional per
+      # field: a nil field is simply absent, and adding a field later does
+      # not add a branch. Pairs rather than a Hash, because two issues can
+      # share a severity and a Hash would silently drop one.
+      def rows(inspection)
+        [
+          ["format", inspection.format], *dimension_rows(inspection),
+          ["dpi", inspection.dpi], ["color space", inspection.color_space],
+          *meta_rows(inspection), ["parse status", inspection.parse_status],
+          *inspection.issues.map { |issue| [issue.severity, issue.message] }
+        ]
+      end
+
+      # Metadata keys come out of the file, and an SVG root may declare
+      # any attribute it likes. Unprefixed, `error="forged"` printed a
+      # line shaped exactly like an issue and `format="png"` printed a
+      # second, contradictory format line. The prefix keeps the file's
+      # own words in their own namespace.
+      #
+      # It settles a collision that was already there, too: an SVG
+      # declaring `width="10mm"` produced a `width` line for the raw
+      # declaration and another for the computed 37.79 px.
+      def meta_rows(inspection)
+        inspection.meta.to_a.sort.map { |key, value| ["meta.#{key}", value] }
+      end
+
+      # One line when both are known, separate lines when only one is.
+      # SVG can carry a width and no height, and "7.0x" is not a
+      # dimension -- but dropping the line would lose the width entirely.
+      def dimension_rows(inspection)
+        width = inspection.width
+        height = inspection.height
+        return [["dimensions", "#{width}x#{height}"]] if width && height
+
+        [["width", width], ["height", height]]
+      end
     end
 
-    desc "validate FILE_PATTERN", "Validate image files (placeholder)"
-    long_desc <<~LONGDESC
-      Validate image files against their respective standards.
+    private_constant :Presenter
+
+    # Turns an exception into a process status. `run` returns an Integer
+    # for everything it maps, and never exits -- only exe/claricle exits,
+    # so every code is reachable from a spec without trapping SystemExit.
+    # Interrupt and other signals are deliberately not mapped and do
+    # propagate, so Ctrl-C behaves like Ctrl-C.
+    module Runner
+      # A command sets its status by returning one of these. A bare Integer
+      # is ignored, because thor passes a command's return value straight
+      # through and any incidental `File.write` would otherwise become the
+      # exit status.
+      class Status
+        RANGE = (0..255)
+        private_constant :RANGE
+
+        attr_reader :code
+
+        def initialize(code)
+          unless self.class.valid?(code)
+            raise ArgumentError, "status must be an Integer in #{RANGE}, got #{code.inspect}"
+          end
+
+          @code = code
+          freeze
+        end
+
+        def self.valid?(code)
+          code.is_a?(Integer) && RANGE.cover?(code)
+        end
+      end
+
+      # Errors Claricle recognises, whose own message already reads as a
+      # sentence. Everything else gets its class named.
+      MAPPED = [Error, Thor::Error, Errno::ENOENT].freeze
+      private_constant :MAPPED
+
+      class << self
+        def run(argv, output: $stderr)
+          arguments = argv.dup
+          validate_arguments(arguments)
+          normalize_command_arguments(arguments)
+          result = invoke(arguments)
+          result.is_a?(Status) ? result.code : 0
+        rescue SystemExit => e
+          # A command may exit deliberately. The status still has to be a
+          # byte: `exit 256` reports success.
+          bounded_status(e.status)
+        rescue StandardError, ScriptError, SystemStackError => e
+          report(error_message(e), output)
+          exit_code(e)
+        end
+
+        private
+
+        # Thor's public `start` turns every EPIPE into success, including
+        # one raised by a command's own operation. Dispatch directly so the
+        # runner can map those failures; Cli handles only its output writes.
+        def invoke(arguments)
+          Cli.send(:dispatch, nil, arguments, nil, { shell: Thor::Base.shell.new })
+        end
+
+        # Thor assumes argv text is valid and ASCII-compatible. Reject input
+        # it cannot parse as a bad invocation instead of an internal error.
+        def validate_arguments(arguments)
+          arguments.each_with_index do |argument, index|
+            valid = argument.is_a?(String) &&
+                    argument.encoding.ascii_compatible? &&
+                    argument.valid_encoding?
+            next if valid
+
+            raise InvocationError, "argument #{index + 1} must be valid ASCII-compatible text"
+          end
+        end
+
+        # Command names are semantic text, unlike future positional paths.
+        # Thor compares them with UTF-8 command keys and can choke on another
+        # valid ASCII-compatible encoding, so normalize only that boundary.
+        def normalize_command_arguments(arguments)
+          command_name = arguments[0]
+          # A leading terminator selects Thor's default command without itself
+          # becoming a command name; leave it in argv for Thor to consume.
+          command_name = nil if command_name == "--"
+          arguments[0] = command_name = command_text(command_name) if command_name
+          return unless help_command?(command_name) && arguments[1]
 
-      This command will validate PNG, SVG, and other image formats
-      for conformance and correctness.
+          arguments[1] = command_text(arguments[1])
+        end
 
-      Note: This is a placeholder command. Functionality will be
-      implemented in future versions.
+        def command_text(argument)
+          argument.encode(Encoding::UTF_8)
+        rescue EncodingError
+          raise InvocationError, "command name cannot be converted to UTF-8"
+        end
 
-      Examples:
-        claricle validate image.png
-        claricle validate *.svg
-        claricle validate "images/*.png"
-    LONGDESC
-    def validate(_pattern)
-      puts "Image validation functionality coming soon!"
-      puts "This gem is currently a placeholder to reserve the name."
+        def help_command?(name)
+          Cli.send(:normalize_command_name, name) == "help"
+        end
+
+        # Writing the diagnostic must not become the failure. `output.puts`
+        # sits inside a rescue body, so nothing above catches it: with
+        # stderr on a closed pipe the EPIPE escaped `run` entirely and the
+        # executable exited 1 -- the status the README reserves for a
+        # nonconformant file. Failing to *report* an error cannot be
+        # allowed to replace that error's own status.
+        def report(message, output)
+          output.puts(message)
+        rescue StandardError
+          nil
+        end
+
+        # Returns rather than raises: an ArgumentError from here would be
+        # inside the SystemExit rescue and could not reach the next clause.
+        def bounded_status(code)
+          Status.valid?(code) ? code : 4
+        end
+
+        # The library owns the map, because a batch has to reach the same
+        # answer for the same exception. Thor's own errors are the one row
+        # that belongs here: they cannot arise inside an operation, and
+        # Fault is deliberately Thor-free.
+        def exit_code(error)
+          error.is_a?(Thor::Error) ? 2 : Fault.exit_code(error)
+        end
+
+        # An unexpected failure names its class: "claricle: missing gem" is
+        # not much help when the class was LoadError. A recognised error
+        # does not need one -- ENOENT included, now that `inspect` takes a
+        # path and a typo is an ordinary user error rather than a defect.
+        def error_message(error)
+          message = Presenter.visible(Fault.message(error))
+          # Errno::ENOENT joins the bare-message set now that a command
+          # takes a path. It was already exit code 2, but its message was
+          # unreachable while nothing opened a file, so naming the class
+          # went unnoticed. A missing file is an ordinary user mistake and
+          # reads as one.
+          return "claricle: #{message}" if MAPPED.any? { |kind| Fault.matches_class?(error, kind) }
+
+          "claricle: #{Fault.class_name(error)}: #{message}"
+        end
+      end
     end
 
-    desc "convert SOURCE DEST", "Convert image formats (placeholder)"
-    long_desc <<~LONGDESC
-      Convert images between different formats.
+    private
 
-      Note: This is a placeholder command. Functionality will be
-      implemented in future versions.
+    def tolerate_closed_output
+      yield
+    rescue Errno::EPIPE
+      Runner::Status.new(0)
+    end
+
+    # `--output -` puts converted bytes alone on stdout; `--json` wants the
+    # same stream for its array. Checked here, before `Claricle.convert_batch`
+    # runs anything, so this is a pure invocation error rather than a
+    # partially-converted batch discovering the conflict mid-write.
+    def refuse_stdout_json_conflict
+      return unless options[:output] == Writer::STDOUT_DESTINATION && options[:json]
+
+      raise InvocationError, "--json is not supported with --output -"
+    end
 
-      Examples:
-        claricle convert image.png image.svg
-        claricle convert logo.svg logo.png
-    LONGDESC
-    def convert(_source, _dest)
-      puts "Image conversion functionality coming soon!"
-      puts "This gem is currently a placeholder to reserve the name."
+    # `--output -` always processes exactly one file: `convert_batch`
+    # refuses more than one source whenever `--output` is given at all, so
+    # `result.highest_error` unambiguously means the one write this command
+    # made. `BatchResult#highest_error` returns the actual raised exception
+    # (not the stringified `BatchError` on the item), so `Errno::EPIPE` is
+    # checked directly here.
+    def closed_stdout_write?(result)
+      options[:output] == Writer::STDOUT_DESTINATION && result.highest_error.is_a?(Errno::EPIPE)
     end
 
-    desc "compress FILE_PATTERN", "Compress image files (placeholder)"
-    long_desc <<~LONGDESC
-      Compress image files while maintaining quality.
+    # JSON is always an array, a single result included: a filename may
+    # legally contain glob characters and a shell expands an unquoted glob
+    # before Claricle sees it, so which form the user typed is not knowable
+    # and the shape must not depend on it.
+    #
+    # Human output splits: verdicts to stdout, one line per failed file to
+    # stderr. Skipped entirely when every file failed, so `puts` cannot
+    # print a bare blank line where the JSON form prints a whole array.
+    def write_conformance(result)
+      return puts(Models::BatchItem.to_json(result.items)) if options[:json]
+
+      verdicts = Presenter.conformance(result.items)
+      puts verdicts unless verdicts.empty?
+      Presenter.conformance_failures(result.items).each { |line| warn line }
+    end
+
+    # One line per successfully converted file: source, target format,
+    # written path (or "-"), and the lossiness classification -- the
+    # plan card's required shape. `--output -` already put the converted
+    # bytes on stdout as a side effect inside `Claricle.convert_batch`, so
+    # the summary goes to stderr instead in that mode, keeping the stdout
+    # stream pipe-safe; every other mode prints it to stdout, the same
+    # split `write_conformance` uses for its own verdict/failure halves.
+    # `--json` is unreachable together with stdout mode -- `convert` above
+    # already refuses that combination before this ever runs -- so reading
+    # `options[:json]` here is safe in both modes.
+    def write_convert(result)
+      return puts(Models::BatchItem.to_json(result.items)) if options[:json]
+
+      print_conversion_summary(Presenter.conversions(result.items))
+      print_conversion_warnings(result.items)
+      Presenter.batch_failures(result.items).each { |line| warn line }
+    end
+
+    # `--output -` already sent the classification to stderr in its summary
+    # line, so a second line per file there would only repeat it.
+    def print_conversion_warnings(items)
+      return if options[:output] == Writer::STDOUT_DESTINATION
+
+      Presenter.conversion_warnings(items).each { |line| warn line }
+    end
 
-      Note: This is a placeholder command. Functionality will be
-      implemented in future versions.
+    # The stdout/stderr split `write_convert`'s own comment describes,
+    # pulled out so `write_convert` stays one guard clause plus two calls.
+    def print_conversion_summary(lines)
+      return lines.each { |line| warn line } if options[:output] == Writer::STDOUT_DESTINATION
 
-      Examples:
-        claricle compress image.png
-        claricle compress *.jpg
-    LONGDESC
-    def compress(_pattern)
-      puts "Image compression functionality coming soon!"
-      puts "This gem is currently a placeholder to reserve the name."
+      puts lines.join("\n") unless lines.empty?
     end
   end
 end

data/lib/claricle/conformance_options.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Claricle
+  # Validates and normalizes the profile/level pair shared by the module
+  # API and Image. A format is optional because batch calls reject global
+  # typos before opening files, then Image checks each concrete pairing.
+  module ConformanceOptions
+    module_function
+
+    def normalize(profile, level, format: nil)
+      profile = profile_name(profile)
+      raise InvocationError, "level requires a profile" if profile.nil? && !level.nil?
+
+      check_format(profile, format) if profile && format
+      [profile, level_name(profile, level)]
+    end
+
+    def profile_name(profile)
+      return if profile.nil?
+
+      wanted = profile.to_sym
+      return wanted if Registry.profiles.include?(wanted)
+
+      raise InvocationError, "no format defines a profile named #{profile.inspect}"
+    end
+
+    def check_format(profile, format)
+      accepted = Registry.profiles_for(format)
+      raise UnsupportedProfile.new(format, profile, accepted) unless accepted.include?(profile)
+    end
+
+    def level_name(profile, level)
+      return if level.nil?
+
+      accepted = Registry.levels_for_profile(profile)
+      raise InvocationError, "profile #{profile} does not take a level" unless accepted
+
+      normalized = level.to_s.downcase.to_sym
+      return normalized if accepted.include?(normalized)
+
+      raise InvocationError,
+            "profile #{profile} does not define level #{level.inspect}; choose #{accepted.join(", ")}"
+    end
+
+    private_class_method :profile_name, :check_format, :level_name
+  end
+
+  private_constant :ConformanceOptions
+end

data/lib/claricle/conversion_engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Claricle
+  # Loads the render stack only when a conversion has passed its local
+  # target and input-size checks. Inspection and conformance do not need it.
+  module ConversionEngine
+    module_function
+
+    def load!
+      require "vectory"
+      require "postsvg"
+
+      # postsvg 0.3.0 declares UnknownOperator through the wrong autoload
+      # path. Loading every operator category once prevents a cold process
+      # from failing only when a rendered SVG contains an embedded raster.
+      ::Postsvg::Model::Operators.load_all!
+    end
+  end
+
+  private_constant :ConversionEngine
+end

data/lib/claricle/convert.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Claricle
+  # One file in, the one `Models::Conversion` out. The same code path as
+  # `convert_batch`, so the write lifecycle, collision and overwrite rules
+  # cannot differ; the only change is the failure shape. A batch collects
+  # a per-file failure into its result, but with one file there is nothing
+  # to carry it past, so the real exception is raised, as `conform?` does.
+  #
+  # `path` is one file, never a pattern: a name that matches several files
+  # is refused before anything is converted.
+  def self.convert(path, to: nil, output: nil, force: false)
+    files = Batch.expand([path], nil)
+    raise InvocationError, "convert takes a single source; #{files.length} files matched" if files.length > 1
+
+    result = convert_batch(files.first, to: to, output: output, force: force)
+    raise result.highest_error if result.highest_error
+
+    result.items.first.result
+  end
+end