claricle 0.1.0 → 0.2.0

data/lib/claricle/handlers/pdf_arlington/definitions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "kind"
+
+module Claricle
+  module Handlers
+    module PdfArlington
+      # Chooses the Arlington table a value is checked against.
+      module Definitions
+        LINK_GROUP = /\A\[([\w,-]+)\]\z/
+
+        module_function
+
+        # The one candidate table for this value, or nil. With several
+        # candidates (`[PageTreeNode,PageObject]`) the value's own /Type
+        # must single one out; otherwise no claim is made.
+        def pick(names, dict)
+          candidates = names.filter_map { |name| load(name) }
+          return candidates.first if candidates.one?
+
+          matching = candidates.select { |candidate| types_of(candidate).include?(dict&.fetch(:Type, nil).to_s) }
+          matching.first if matching.one?
+        end
+
+        def types_of(definition)
+          definition.field_for("Type")&.possible_value_list || []
+        end
+
+        def load(name)
+          ::Pdfrb::Arlington::Loader.object_definition(name)
+        rescue ::Pdfrb::Error
+          nil
+        end
+
+        # One link group per type in the field's type list (`array;stream`
+        # pairs with `[A];[B]`): the group of the type the value really is.
+        def link_names(field, kind)
+          match = LINK_GROUP.match(link_group(field, kind).to_s)
+          match && match[1].split(",")
+        end
+
+        def link_group(field, kind)
+          types = field.types_raw.split(";").map(&:strip)
+          groups = field.link.to_s.split(";")
+          return groups.first if types.one?
+          return unless groups.size == types.size
+
+          index = types.index { |type| Kind::ACCEPTS[type]&.include?(kind) }
+          groups[index] if index
+        end
+      end
+    end
+  end
+end

data/lib/claricle/handlers/pdf_arlington/kind.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Claricle
+  module Handlers
+    module PdfArlington
+      # Maps a Ruby value read from pdfrb onto the Arlington type names it
+      # satisfies. A kind of nil means "not one pdfrb type this table knows",
+      # and the caller then makes no claim about the value.
+      module Kind
+        ACCEPTS = {
+          "integer" => %i[integer], "bitmask" => %i[integer], "number" => %i[integer number],
+          "boolean" => %i[boolean], "name" => %i[name], "null" => %i[null], "stream" => %i[stream],
+          "string" => %i[string], "string-ascii" => %i[string], "string-byte" => %i[string],
+          "string-text" => %i[string], "date" => %i[string],
+          "dictionary" => %i[dictionary], "name-tree" => %i[dictionary],
+          "number-tree" => %i[dictionary],
+          "array" => %i[array], "rectangle" => %i[array], "matrix" => %i[array]
+        }.freeze
+
+        CLASS_KINDS = {
+          ::Hash => :dictionary, ::Array => :array, ::Symbol => :name, ::Integer => :integer,
+          ::Float => :number, ::String => :string, ::NilClass => :null,
+          ::TrueClass => :boolean, ::FalseClass => :boolean
+        }.freeze
+
+        CONTAINERS = %i[dictionary stream array].freeze
+
+        module_function
+
+        # A stream keeps its wrapper (the dictionary is only part of it); any
+        # other pdfrb object is reduced to the plain value it holds.
+        def plain(object)
+          return object if stream?(object)
+
+          object.respond_to?(:value) ? object.value : object
+        end
+
+        def stream?(object)
+          ::Pdfrb::Model::Cos::Stream === object # rubocop:disable Style/CaseEquality
+        end
+
+        def of(value)
+          return :stream if stream?(value)
+
+          CLASS_KINDS.find { |klass, _| value.is_a?(klass) }&.last
+        end
+
+        # The Arlington type names of a field, or nil when any of them is a
+        # predicate (`fn:SinceVersion(1.3,dictionary)`) this walker does not
+        # evaluate -- a partly understood type list is not checked.
+        def types(field)
+          names = field.types_raw.split(";").map(&:strip)
+          names if names.any? && names.all? { |name| ACCEPTS.key?(name) }
+        end
+
+        def allows?(names, kind)
+          names.any? { |name| ACCEPTS.fetch(name).include?(kind) }
+        end
+      end
+    end
+  end
+end

data/lib/claricle/handlers/pdf_arlington/predicate_gate.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Claricle
+  module Handlers
+    module PdfArlington
+      # Runs a field's `fn:IsRequired(...)` predicate through pdfrb's
+      # evaluator. pdfrb 0.7.49 does not parse every predicate in its own
+      # tables (measured: 78 of 192 Required predicates raise SyntaxError)
+      # and lacks some functions, so anything it cannot parse or run is
+      # "not known to be required" -- never an issue.
+      class PredicateGate
+        def initialize(version)
+          @version = version
+          @parsed = {}
+        end
+
+        def required?(source, dict)
+          ast = @parsed.fetch(source) { @parsed[source] = parse(source) }
+          ast ? evaluate(ast, dict) == true : false
+        end
+
+        private
+
+        def parse(source)
+          ::Pdfrb::Arlington::Predicate::Parser.parse(source)
+        rescue ::Pdfrb::Error
+          nil
+        end
+
+        def evaluate(ast, dict)
+          context = ::Pdfrb::Arlington::Predicate::Context.new(current: dict, version: @version)
+          ::Pdfrb::Arlington::Predicate::Evaluator.call(ast, context)
+        rescue ::Pdfrb::Error, NoMethodError, TypeError, ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/claricle/handlers/pdf_arlington/rules.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../../models/issue"
+require_relative "../../models/location"
+require_relative "kind"
+require_relative "predicate_gate"
+
+module Claricle
+  module Handlers
+    module PdfArlington
+      # What Arlington says about ONE dictionary or ONE value, as Issues.
+      # Knows nothing about traversal.
+      class Rules
+        REQUIRED_CODE = "PDF_ARLINGTON_REQUIRED_KEY"
+        TYPE_CODE = "PDF_ARLINGTON_TYPE"
+        VALUE_CODE = "PDF_ARLINGTON_VALUE"
+
+        # `[Pages]` or `[1.0,1.1]`: plain tokens only, so a predicate
+        # (`[fn:Eval(...)]`) or a wildcard is never read as a literal.
+        PLAIN_VALUES = /\A\[([^\[\]()@*;]+)\]\z/
+
+        def initialize(version)
+          @version = version
+          @gate = PredicateGate.new(version)
+        end
+
+        # `inherited` answers "does an ancestor supply this key", for the
+        # fields Arlington marks inheritable (a Page's /Resources, /MediaBox).
+        def dictionary_issues(definition, dict, path, inherited)
+          definition.fields.filter_map do |field|
+            next unless missing_required?(field, dict, inherited)
+
+            issue(REQUIRED_CODE, "#{definition.name} is missing required key /#{field.key}", path)
+          end
+        end
+
+        def value_issues(field, kind, value, path)
+          return [] if kind.nil?
+
+          [type_issue(field, kind, path), name_issue(field, kind, value, path)].compact
+        end
+
+        private
+
+        def missing_required?(field, dict, inherited)
+          return false if field.key == "*" || !dict[field.key.to_sym].nil? || !applies?(field)
+          return false if field.inheritable? && inherited.call(field.key)
+
+          required_now?(field, dict)
+        end
+
+        def required_now?(field, dict)
+          field.required? || (field.required_predicate? && @gate.required?(field.required_literal, dict))
+        end
+
+        # A key added after the document's version, or by an extension, is
+        # not required of it.
+        def applies?(field)
+          field.since_version.extensions.empty? && (field.since_version <=> @version) <= 0
+        end
+
+        def type_issue(field, kind, path)
+          names = Kind.types(field)
+          return if names.nil? || kind == :null || Kind.allows?(names, kind)
+
+          issue(TYPE_CODE, "#{path} is a #{kind}; Arlington allows #{names.join(" or ")}", path)
+        end
+
+        def name_issue(field, kind, value, path)
+          return unless kind == :name && field.types_raw == "name"
+
+          match = PLAIN_VALUES.match(field.possible_values.to_s)
+          allowed = match && match[1].split(",").map(&:strip)
+          return if allowed.nil? || allowed.include?(value.to_s)
+
+          issue(VALUE_CODE, "#{path} is /#{value}; Arlington allows #{allowed.join(", ")}", path)
+        end
+
+        def issue(code, message, path)
+          Models::Issue.new(severity: "error", code: code, message: message,
+                            location: Models::Location.new(node_path: path))
+        end
+      end
+    end
+  end
+end

data/lib/claricle/handlers/pdf_arlington/walker.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "../../models/issue"
+require_relative "definitions"
+require_relative "kind"
+require_relative "rules"
+
+module Claricle
+  module Handlers
+    module PdfArlington
+      # Walks a parsed document breadth-first from the Catalog, following
+      # every link Arlington's tables name, and collects what `Rules` finds.
+      #
+      # Bounded three ways: an object reached through a reference is
+      # visited once (cycles end), the walk is a worklist rather than
+      # recursion (depth costs no stack), and it stops after MAX_NODES
+      # values with a warning that says it stopped.
+      class Walker
+        MAX_NODES = 50_000
+        LIMIT_CODE = "PDF_ARLINGTON_LIMIT"
+        MAX_ANCESTORS = 64
+
+        Item = Data.define(:value, :field, :names, :path)
+
+        def initialize(document, version)
+          @document = document
+          @rules = Rules.new(version)
+          @issues = []
+          @seen = {}
+        end
+
+        def issues
+          queue = [Item.new(@document.catalog, nil, %w[Catalog], "Catalog")]
+          count = 0
+          until queue.empty?
+            return limit_reached if (count += 1) > MAX_NODES || count + queue.size > MAX_NODES * 2
+
+            visit(queue.shift, queue)
+          end
+          @issues
+        end
+
+        private
+
+        def visit(item, queue)
+          value = Kind.plain(resolve(item.value))
+          kind = Kind.of(value)
+          @issues.concat(@rules.value_issues(item.field, kind, value, item.path)) if item.field
+          return unless Kind::CONTAINERS.include?(kind) && first_visit?(item.value)
+
+          definition = definition_for(item, value, kind)
+          descend(definition, value, kind, item.path, queue) if definition
+        end
+
+        def definition_for(item, value, kind)
+          names = item.names || Definitions.link_names(item.field, kind)
+          names && Definitions.pick(names, kind == :array ? nil : dictionary_of(value))
+        end
+
+        def descend(definition, value, kind, path, queue)
+          dict = kind == :array ? nil : dictionary_of(value)
+          check(definition, dict, path) if dict
+          entries(dict || value).each do |key, child, child_path|
+            field = definition.field_for(key.to_s) || definition.field_for("*")
+            queue << Item.new(child, field, nil, "#{path}#{child_path}") if field
+          end
+        end
+
+        def check(definition, dict, path)
+          @issues.concat(@rules.dictionary_issues(definition, dict, path, ->(key) { inherited?(dict, key) }))
+        end
+
+        def entries(container)
+          if container.is_a?(::Hash)
+            container.map { |key, child| [key, child, "/#{key}"] }
+          else
+            container.each_with_index.map { |child, index| [index, child, "[#{index}]"] }
+          end
+        end
+
+        def dictionary_of(value)
+          Kind.stream?(value) ? value.value : value
+        end
+
+        def first_visit?(raw)
+          return true unless raw.is_a?(::Pdfrb::Model::Reference)
+
+          @seen.key?(raw.oid) ? false : (@seen[raw.oid] = true)
+        end
+
+        # Walks /Parent upward, never revisiting an object and never more
+        # than MAX_ANCESTORS steps, so a looping page tree ends.
+        def inherited?(dict, key)
+          seen = {}
+          current = dict
+          MAX_ANCESTORS.times do
+            current = parent_of(current, seen)
+            return false unless current
+            return true unless current[key.to_sym].nil?
+          end
+          false
+        end
+
+        def parent_of(dict, seen)
+          parent = dict[:Parent]
+          return unless parent.is_a?(::Pdfrb::Model::Reference) && !seen.key?(parent.oid)
+
+          seen[parent.oid] = true
+          resolved = Kind.plain(resolve(parent))
+          resolved if resolved.is_a?(::Hash)
+        end
+
+        # nil when pdfrb cannot produce the object. Everything pdfrb
+        # reports by raising on a malformed file is "no object here"; the
+        # structural check owns reporting the file as broken.
+        def resolve(value)
+          @document.object(value)
+        rescue ::Pdfrb::Error, NoMethodError, TypeError, ArgumentError
+          nil
+        end
+
+        def limit_reached
+          @issues << Models::Issue.new(
+            severity: "warning", code: LIMIT_CODE,
+            message: "Arlington check stopped after #{MAX_NODES} values; the rest was not checked"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/claricle/handlers/pdf_arlington.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "pdf_arlington/walker"
+
+module Claricle
+  module Handlers
+    # Arlington-model conformance for a parsed pdfrb document: required
+    # keys, value types and enumerated names, checked from the Catalog
+    # down. pdfrb ships Arlington's tables, predicate evaluator and
+    # loader but no document runner (measured on 0.7.49), so the walk is
+    # ours.
+    module PdfArlington
+      module_function
+
+      # `document` is a `Pdfrb::Document`. Returns an Array of
+      # `Models::Issue`; empty when the document has no Catalog (the
+      # structural check reports that).
+      def issues(document)
+        return [] unless catalog?(document)
+
+        Walker.new(document, version_of(document)).issues
+      end
+
+      # A Catalog that cannot be read is the structural check's finding.
+      def catalog?(document)
+        Kind.plain(document.catalog).is_a?(::Hash)
+      rescue ::Pdfrb::Error, NoMethodError, SystemStackError
+        false
+      end
+
+      def version_of(document)
+        ::Pdfrb::Arlington::PdfVersion.new(document.version.to_s)
+      rescue ::Pdfrb::Error, ArgumentError
+        ::Pdfrb::Arlington::PdfVersion.new("1.0")
+      end
+    end
+  end
+end

data/lib/claricle/handlers/pdf_profiles.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../models/issue"
+require_relative "../models/location"
+
+module Claricle
+  module Handlers
+    # Dispatches pdfrb's named conformance families and maps their typed
+    # violations into Claricle's common issue model.
+    class PdfProfiles
+      PROFILE_LEVELS = {
+        pdf_a: %i[a1b a1a a2b a2a a3b a3a a4].freeze,
+        pdf_ua: nil,
+        pdf_x: %i[x1a x3 x4 x6].freeze,
+        pdf_vt: %i[vt1 vt2].freeze,
+        pades: %i[b-b b-t b-lt b-lta].freeze,
+        ltv: nil,
+        pdf_2_af: nil,
+        tagged_pdf: nil
+      }.freeze
+      VALIDATORS = {
+        pdf_a: :PdfA,
+        pdf_ua: :PdfUA,
+        pdf_x: :PdfX,
+        pdf_vt: :PdfVT,
+        pades: :Pades,
+        ltv: :Ltv,
+        pdf_2_af: :Pdf2AF,
+        tagged_pdf: :TaggedPdf
+      }.freeze
+      PADES_LEVELS = {
+        "b-b": :"B-B", "b-t": :"B-T",
+        "b-lt": :"B-LT", "b-lta": :"B-LTA"
+      }.freeze
+      private_constant :PROFILE_LEVELS, :VALIDATORS, :PADES_LEVELS
+
+      def self.profiles = PROFILE_LEVELS.keys
+
+      def self.levels_for(profile) = PROFILE_LEVELS.fetch(profile)
+
+      def self.issues(document, profile, level)
+        validator = ::Pdfrb::Conformance.const_get(VALIDATORS.fetch(profile))
+        arguments = level ? { level: delegate_level(profile, level) } : {}
+        validator.validate(document, **arguments).violations.map { |violation| issue(violation) }
+      end
+
+      def self.delegate_level(profile, level)
+        profile == :pades ? PADES_LEVELS.fetch(level) : level
+      end
+      private_class_method :delegate_level
+
+      def self.issue(violation)
+        location = violation.object && Models::Location.new(node_path: violation.object.to_s)
+        Models::Issue.new(
+          severity: violation.severity.to_s,
+          code: violation.rule_id.to_s,
+          message: violation.message,
+          location: location
+        )
+      end
+      private_class_method :issue
+    end
+
+    private_constant :PdfProfiles
+  end
+end