claricle 0.1.0 → 0.2.0

data/lib/claricle.rb

@@ -2,15 +2,252 @@
 
 require "thor"
 require_relative "claricle/version"
+require_relative "claricle/errors"
+require_relative "claricle/models/location"
+require_relative "claricle/models/issue"
+require_relative "claricle/models/report"
+require_relative "claricle/models/inspection"
+require_relative "claricle/lossiness"
+require_relative "claricle/models/conversion"
+require_relative "claricle/models/batch_item"
+require_relative "claricle/models/format_capability"
+require_relative "claricle/fault"
+require_relative "claricle/batch"
+require_relative "claricle/writer"
+require_relative "claricle/registry"
+require_relative "claricle/conformance_options"
+require_relative "claricle/detector"
+require_relative "claricle/image"
+require_relative "claricle/cli"
+require_relative "claricle/convert"
 
 module Claricle
-  class Error < StandardError; end
+  # Detects the format of `source`, a String of image content or an IO.
+  #
+  # An IO is read from wherever it is currently positioned -- it is never
+  # rewound, so a caller who has already consumed part of it gets a
+  # verdict on the remainder. Bytes are pulled in incrementally and
+  # classification is retried after each read, so a short, conclusive
+  # image (its signature or root tag already present) returns without
+  # waiting for more. Plain PostScript and EPSF are the exception: a byte
+  # that hasn't arrived yet can still turn one into the other, so that
+  # verdict waits for the probe bound -- the largest amount any detector
+  # probe consults -- or end of stream. A binary-preview EPS has its own
+  # conclusive magic and returns immediately. A source that stays open
+  # and never supplies enough to decide blocks until one of those is
+  # reached; content beyond the bound is left unread on the IO rather
+  # than buffered. It should be in binary mode; newline translation
+  # would corrupt the signatures this matches on. Pass a path to
+  # `Image.from_path` to stream from a file instead of buffering.
+  def self.detect(source)
+    return Detector.detect(source) unless source.respond_to?(:read)
 
-  # Future component loading will go here:
-  # require_relative "claricle/png_validator"
-  # require_relative "claricle/svg_processor"
-  # require_relative "claricle/vector_converter"
-  # require_relative "claricle/image_compressor"
+    Detector.detect(accumulate(source))
+  end
 
-  require_relative "claricle/cli"
+  # Grows `buffer` by reading from `source` a chunk at a time, stopping
+  # as soon as the buffer classifies, hits the probe bound, or the
+  # source ends -- so a complete short image on a stream that never
+  # closes doesn't wait for bytes nothing needs.
+  def self.accumulate(source)
+    buffer = "".b
+    loop do
+      return buffer if conclusive?(buffer) || buffer.bytesize >= Detector::MAX_PROBE_BYTES
+
+      begin
+        buffer << source.readpartial(Detector::MAX_PROBE_BYTES - buffer.bytesize)
+      rescue EOFError
+        return buffer
+      end
+    end
+  end
+
+  def self.conclusive?(buffer)
+    return true if EpsBinary.wrapped?(buffer)
+
+    format = Detector.detect(buffer)
+    # A plain PostScript verdict is provisional until the underlying line
+    # scan is certain: a byte that hasn't arrived yet can still flip EPSF
+    # from a trusted match to a disqualified one, so this loop must not
+    # settle for less than a real end of stream or the probe bound.
+    !%i[ps eps].include?(format)
+  rescue UnknownFormat
+    false
+  end
+
+  # Does everything named here conform? Exactly one of a positional path or
+  # `pattern:` -- issue #1's own examples use both shapes.
+  #
+  # A predicate answers about conformance and raises about everything else.
+  # A nonconformant file is `false`; an unknown format, an unsupported one,
+  # a missing file or a delegate crash raises, out of the batch shape too,
+  # so an operational failure never reads as a verdict.
+  #
+  # Both shapes reach the same expansion, so a positional means here exactly
+  # what it means on the command line: a literal path when it names a file,
+  # and a glob otherwise.
+  def self.conform?(path = nil, pattern: nil, strict: false, profile: nil, level: nil)
+    raise InvocationError, "give exactly one of a path or pattern" unless path.nil? ^ pattern.nil?
+
+    profile, level = ConformanceOptions.normalize(profile, level)
+    result = conformance_batch(*[path].compact, pattern: pattern,
+                                                strict: strict, profile: profile, level: level)
+    raise result.highest_error if result.highest_error
+
+    result.exit_code.zero?
+  end
+
+  def self.conformance_report(path, profile: nil, level: nil)
+    profile, level = ConformanceOptions.normalize(profile, level)
+    Image.from_path(path).conformance_report(profile: profile, level: level)
+  end
+
+  # A batch predicate loses information, so a caller can have the whole
+  # result instead: ordered per-file outcomes plus the aggregate status,
+  # which is what the command prints. Takes the command's own argument
+  # shape -- files, a pattern, or both -- so the two cannot drift about
+  # what conformance means.
+  def self.conformance_batch(*paths, pattern: nil, strict: false, profile: nil, level: nil)
+    # Checked eagerly here, before the batch runs, so a profile no format
+    # defines is one invocation error about the call and never a row in a
+    # report -- `conformance_report` checks it again per file, but only as a
+    # no-op once this call has already passed.
+    profile, level = ConformanceOptions.normalize(profile, level)
+    Batch.run(paths, pattern: pattern,
+                     classify: ->(report) { conformant?(report, strict: strict) ? 0 : 1 }) do |file|
+      conformance_report(file, profile: profile, level: level)
+    end
+  end
+
+  # Any error means no; a warning alone means suspicious, which passes
+  # unless the caller asked for strict; info never downgrades anything.
+  def self.conformant?(report, strict:)
+    strict ? report.valid == :yes : report.valid != :no
+  end
+
+  # A batch predicate loses information, so a caller can have the whole
+  # result instead: ordered per-file outcomes plus the aggregate status.
+  # Same argument shape as `conformance_batch` (paths, pattern:), plus
+  # `to:`/`output:`/`force:` for the target and the write lifecycle, so
+  # the CLI command and the Ruby API cannot drift about what "which files"
+  # or "where to" mean.
+  #
+  # The whole destination set is preflighted -- collision, overwrite,
+  # case-fold aliasing -- BEFORE any file is converted. That is why this
+  # resolves the expanded file list and every destination up front, rather
+  # than letting `Batch.run` derive them one file at a time the way
+  # `conformance_batch` does.
+  #
+  # Target resolution runs before the single-source check below, so a
+  # `--to`/`--output` mismatch is reported even when the source count is
+  # also wrong -- the more specific problem surfaces first rather than
+  # being masked by the more generic one.
+  def self.convert_batch(*paths, to: nil, output: nil, force: false, pattern: nil)
+    files = Batch.expand(paths, pattern)
+    target = resolved_convert_target(to: to, output: output)
+    raise InvocationError, "--output takes a single source; #{files.length} files matched" if output && files.length > 1
+
+    destinations = files.to_h { |file| [file, convert_destination(file, target: target, output: output)] }
+    writer = Writer.new(destinations.values, sources: files, force: force)
+
+    # `classify` always answers 0: the block below either returns a
+    # `Models::Conversion` normally, or raises, which Batch's own per-file
+    # rescue already turns into a failed item with its own exit code. There
+    # is no success/failure distinction left for `classify` to make --
+    # unlike `Report#valid`, a completed conversion has no verdict to grade.
+    #
+    # `run_files`, not `run`: `files` is already the expanded list built
+    # above for the destination preflight. `run` would expand it a SECOND
+    # time -- redundant stat/realpath work on every file, and a real gap:
+    # a file removed between the two expansions would silently drop out of
+    # the second one with no error, even though a destination was already
+    # preflighted for it.
+    Batch.run_files(files, classify: ->(_result) { 0 }) do |file|
+      convert_one(file, target: target, destination: destinations.fetch(file), writer: writer)
+    end
+  end
+
+  def self.convert_one(file, target:, destination:, writer:)
+    image = Image.from_path(file)
+    raise InvocationError, "#{file} is already #{target}; nothing to convert to" if image.format == target
+
+    # See `Models::Conversion#with_output_path` for why a second instance
+    # is built here rather than the handler's own carrying the real path.
+    conversion = image.convert(to: target)
+    conversion.with_output_path(writer.write(conversion.content, to: destination))
+  end
+
+  # `--to` wins outright when given, once it does not conflict with a
+  # recognised `--output` extension. `--output` alone must name a
+  # recognised extension to infer from; `--output -` alone cannot, since
+  # stdout has no extension.
+  #
+  # `--to` is case-folded to the registry's own spelling (`Registry.formats`
+  # is always lowercase symbols) so `--to SVG` and `--to svg` resolve
+  # identically -- unfolded, `--to SVG --output copy.svg` reported a false
+  # "conflicts with --output" (the two sides compared `:SVG` against the
+  # inferred `:svg`), a same-format `--to SVG` on an already-SVG source
+  # skipped the guard below entirely, and the derived destination for a
+  # bare `--to SVG` carried the wrong-cased extension.
+  def self.resolved_convert_target(to:, output:)
+    # `if to` alone treats an explicit `--to ""` as given: truthy, but
+    # `to.to_s.downcase.to_sym` then builds the bogus target `:""`, which
+    # went on to derive a destination with no extension and a garbled
+    # "not supported for convert to :\"\"" message instead of the clean
+    # invocation error below. `--to ""` and no `--to` at all mean the same
+    # thing -- there is no target -- so both take this branch.
+    return resolved_to_target(to, output) if to && !to.to_s.empty?
+    if output == Writer::STDOUT_DESTINATION
+      raise InvocationError, "--output - needs --to; there is no extension to infer from"
+    end
+    raise InvocationError, "give --to, or an --output with a recognised format extension" if output.nil?
+
+    convert_extension_format(output) ||
+      raise(InvocationError, "--output #{output.inspect} has no recognised format extension; give --to")
+  end
+
+  def self.resolved_to_target(to, output)
+    target = to.to_s.downcase.to_sym
+    raise InvocationError, "unknown format #{to.to_s.inspect} for --to" unless Registry.formats.include?(target)
+
+    check_to_output_conflict(target, output)
+    target
+  end
+
+  # A conflict, not a preference: one silently winning over the other would
+  # surprise whichever the caller meant. `output:` naming stdout or an
+  # unrecognised extension carries no claim about the target, so there is
+  # nothing for `--to` to conflict with in either case. `target` arrives
+  # already case-folded from `resolved_convert_target`.
+  def self.check_to_output_conflict(target, output)
+    return if output.nil? || output == Writer::STDOUT_DESTINATION
+
+    inferred = convert_extension_format(output)
+    return if inferred.nil? || inferred == target
+
+    raise InvocationError, "--to #{target} conflicts with --output #{output} (looks like #{inferred})"
+  end
+
+  # The canonical extension for a target is the format symbol itself --
+  # there is no central extension table, only `Registry.formats`.
+  def self.convert_extension_format(name)
+    ext = File.extname(name.to_s).delete_prefix(".").downcase
+    return nil if ext.empty?
+
+    format = ext.to_sym
+    Registry.formats.include?(format) ? format : nil
+  end
+
+  # The issue's own example: `convert("diagram.emf", to: :svg)` writes
+  # `diagram.svg` -- the source's own name, the target's extension,
+  # alongside the source.
+  def self.convert_destination(file, target:, output:)
+    return output if output
+
+    File.join(File.dirname(file), "#{File.basename(file, ".*")}.#{target}")
+  end
+
+  private_class_method :accumulate, :conclusive?, :conformant?,
+                       :convert_one, :resolved_convert_target, :resolved_to_target,
+                       :check_to_output_conflict, :convert_extension_format, :convert_destination
 end

metadata

@@ -1,36 +1,175 @@
 --- !ruby/object:Gem::Specification
 name: claricle
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-27 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: emf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: emfsvg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.32
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.32
+- !ruby/object:Gem::Dependency
+  name: pdfrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.23
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.23
+- !ruby/object:Gem::Dependency
+  name: png_conform
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.4
+- !ruby/object:Gem::Dependency
+  name: postscript
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: postsvg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.4
+- !ruby/object:Gem::Dependency
+  name: svg_conform
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.2
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: vectory
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.12.0
 description: |
-  Claricle provides a Ruby library for working with images, offering tools for
-  image validation (PNG, SVG), format conversion, compression, and vector
-  graphics processing. The name combines "clarity" and "particle", representing
-  the clear validation of every pixel. It is built to integrate functionality
-  from pngconform, svgconform, vectory, and other image processing tools into
-  a unified interface.
+  Claricle detects an image's format from its bytes -- PNG, SVG, EMF, WMF,
+  EPS, PS and PDF -- and gives one object and one set of models to work with.
+  The name combines "clarity" and "particle". It inspects, checks
+  conformance and converts between formats, wrapping
+  png_conform, svg_conform, vectory and pdfrb behind a single interface.
 email:
 - open.source@ribose.com
 executables:
@@ -42,21 +181,65 @@ files:
 - ".rubocop.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
+- LICENSE
 - README.adoc
 - Rakefile
-- claricle.gemspec
+- TODO.plan/00-overview.md
+- TODO.plan/01-core.md
+- TODO.plan/02-inspect.md
+- TODO.plan/03-conform.md
+- TODO.plan/04-convert.md
 - exe/claricle
 - lib/claricle.rb
+- lib/claricle/batch.rb
 - lib/claricle/cli.rb
+- lib/claricle/conformance_options.rb
+- lib/claricle/conversion_engine.rb
+- lib/claricle/convert.rb
+- lib/claricle/detector.rb
+- lib/claricle/emf_header.rb
+- lib/claricle/errors.rb
+- lib/claricle/fault.rb
+- lib/claricle/handlers/base.rb
+- lib/claricle/handlers/extension_points.rb
+- lib/claricle/handlers/metafile.rb
+- lib/claricle/handlers/pdf.rb
+- lib/claricle/handlers/pdf_arlington.rb
+- lib/claricle/handlers/pdf_arlington/definitions.rb
+- lib/claricle/handlers/pdf_arlington/kind.rb
+- lib/claricle/handlers/pdf_arlington/predicate_gate.rb
+- lib/claricle/handlers/pdf_arlington/rules.rb
+- lib/claricle/handlers/pdf_arlington/walker.rb
+- lib/claricle/handlers/pdf_profiles.rb
+- lib/claricle/handlers/png.rb
+- lib/claricle/handlers/postscript.rb
+- lib/claricle/handlers/svg.rb
+- lib/claricle/image.rb
+- lib/claricle/lossiness.rb
+- lib/claricle/lossiness/levels.rb
+- lib/claricle/models/base.rb
+- lib/claricle/models/batch_item.rb
+- lib/claricle/models/conversion.rb
+- lib/claricle/models/format_capability.rb
+- lib/claricle/models/free_form_hash.rb
+- lib/claricle/models/inspection.rb
+- lib/claricle/models/issue.rb
+- lib/claricle/models/location.rb
+- lib/claricle/models/report.rb
+- lib/claricle/models/uncoerced_integer.rb
+- lib/claricle/postscript_fidelity.rb
+- lib/claricle/postscript_fidelity/verdict.rb
+- lib/claricle/postscript_fidelity/view_box.rb
+- lib/claricle/registry.rb
 - lib/claricle/version.rb
-- sig/claricle.rbs
-homepage: https://github.com/ribose/claricle
+- lib/claricle/writer.rb
+homepage: https://github.com/claricle/claricle
 licenses:
 - BSD-2-Clause
 metadata:
-  homepage_uri: https://github.com/ribose/claricle
-  source_code_uri: https://github.com/ribose/claricle
-  changelog_uri: https://github.com/ribose/claricle
+  homepage_uri: https://github.com/claricle/claricle
+  source_code_uri: https://github.com/claricle/claricle
+  changelog_uri: https://github.com/claricle/claricle/releases
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -66,7 +249,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -76,6 +259,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Claricle is a comprehensive image utility gem for validation, conversion,
-  and compression.
+summary: Detect, inspect, conform and convert image files in Ruby.
 test_files: []

data/claricle.gemspec

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/claricle/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "claricle"
-  spec.version = Claricle::VERSION
-  spec.authors = ["Ribose Inc."]
-  spec.email = ["open.source@ribose.com"]
-
-  spec.summary = "Claricle is a comprehensive image utility gem for validation, conversion, and compression."
-  spec.description = <<~HEREDOC
-    Claricle provides a Ruby library for working with images, offering tools for
-    image validation (PNG, SVG), format conversion, compression, and vector
-    graphics processing. The name combines "clarity" and "particle", representing
-    the clear validation of every pixel. It is built to integrate functionality
-    from pngconform, svgconform, vectory, and other image processing tools into
-    a unified interface.
-  HEREDOC
-
-  spec.homepage = "https://github.com/ribose/claricle"
-  spec.license = "BSD-2-Clause"
-  spec.required_ruby_version = ">= 3.0.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ribose/claricle"
-  spec.metadata["changelog_uri"] = "https://github.com/ribose/claricle"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # 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(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "thor", "~> 1.0"
-end

data/sig/claricle.rbs

@@ -1,4 +0,0 @@
-module Claricle
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end