invoice_extractor_arca 0.2.0

data/lib/invoice_extractor_arca/dependencies/resolver.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module InvoiceExtractorArca
+  module Dependencies
+    class Resolver
+      REQUIRED = %i[
+        pdftoppm
+        pdftotext
+        zbarimg
+      ].freeze
+
+      def initialize(custom_paths: {}, path_env: ENV["PATH"])
+        @custom_paths = normalize_keys(custom_paths || {})
+        @path_env = path_env.to_s
+      end
+
+      def resolve!(name)
+        name = name.to_sym
+        custom_path = @custom_paths[name]
+
+        return validate_custom!(name, custom_path) if custom_path
+
+        find_on_path(name.to_s) || raise_missing(name)
+      end
+
+      def resolve_all!(*names)
+        names = REQUIRED if names.empty?
+
+        missing = []
+        resolved = {}
+
+        names.each do |name|
+          resolved[name.to_sym] = resolve!(name)
+        rescue Errors::MissingDependency
+          missing << name.to_sym
+        end
+
+        raise_missing_group(missing) unless missing.empty?
+
+        resolved
+      end
+
+      def check_all(*names)
+        names = REQUIRED if names.empty?
+
+        names.each_with_object({}) do |name, results|
+          results[name.to_sym] = {
+            available: true,
+            path: resolve!(name),
+            error: nil
+          }
+        rescue Errors::MissingDependency => e
+          results[name.to_sym] = {
+            available: false,
+            path: nil,
+            error: e.message
+          }
+        end
+      end
+
+      private
+
+      def normalize_keys(hash)
+        hash.each_with_object({}) do |(key, value), normalized|
+          normalized[key.to_sym] = value
+        end
+      end
+
+      def validate_custom!(name, path)
+        expanded = File.expand_path(path.to_s)
+
+        return expanded if File.file?(expanded) && File.executable?(expanded)
+
+        raise Errors::MissingDependency.new(
+          "Configured #{name} is not executable: #{expanded}",
+          missing: [name]
+        )
+      end
+
+      def find_on_path(command)
+        @path_env.split(File::PATH_SEPARATOR).each do |directory|
+          next if directory.to_s.empty?
+
+          candidate = File.join(directory, command)
+
+          if File.file?(candidate) && File.executable?(candidate)
+            return File.expand_path(candidate)
+          end
+        end
+
+        nil
+      end
+
+      def raise_missing(name)
+        raise Errors::MissingDependency.new(
+          missing_dependency_message([name]),
+          missing: [name]
+        )
+      end
+
+      def raise_missing_group(names)
+        raise Errors::MissingDependency.new(
+          missing_dependency_message(names),
+          missing: names
+        )
+      end
+
+      def missing_dependency_message(names)
+        commands = names.join(", ")
+
+        "Missing external dependency: #{commands}. " \
+          "Install the missing command or configure dependency_paths."
+      end
+    end
+  end
+end

data/lib/invoice_extractor_arca/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module InvoiceExtractorArca
+  class Error < StandardError
+  end
+end

data/lib/invoice_extractor_arca/error_record.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module InvoiceExtractorArca
+  class ErrorRecord
+    attr_reader :code, :message, :severity, :component, :details
+
+    def initialize(
+      code:,
+      message:,
+      severity: "error",
+      component: nil,
+      details: {}
+    )
+      @code = code.to_s
+      @message = message.to_s
+      @severity = severity.to_s
+      @component = component&.to_s
+      @details = details || {}
+    end
+
+    def error?
+      severity == "error"
+    end
+
+    def warning?
+      severity == "warning"
+    end
+
+    def to_h
+      {
+        code: code,
+        message: message,
+        severity: severity,
+        component: component,
+        details: details
+      }.compact
+    end
+  end
+end

data/lib/invoice_extractor_arca/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module InvoiceExtractorArca
+  module Errors
+    class MissingDependency < Error
+      attr_reader :missing
+
+      def initialize(message = nil, missing: [])
+        @missing = Array(missing)
+        super(message || "Missing external dependency: #{missing.join(", ")}")
+      end
+    end
+
+    class UnsupportedFileType < Error
+    end
+
+    class UnreadableFile < Error
+    end
+
+    class QrNotFound < Error
+    end
+
+    class InvalidVoucherSchema < Error
+    end
+
+    class MultipleQrFound < Error
+    end
+
+    class PdfTextExtractionFailure < Error
+    end
+  end
+end

data/lib/invoice_extractor_arca/extractor.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "result"
+require_relative "errors"
+require_relative "error_record"
+require_relative "command_runner"
+require_relative "dependencies/resolver"
+require_relative "qr_extractor"
+require_relative "voucher_validator"
+require_relative "pdf/text_extractor"
+require_relative "text/normalizer"
+require_relative "ocr/rapidocr_text_extractor"
+require_relative "final_payload_builder"
+
+module InvoiceExtractorArca
+  class Extractor
+    def initialize(
+      strict: false,
+      dependency_paths: {},
+      page_range: nil,
+      resolution: 300,
+      multiple_qr: :first_valid,
+      qr_scanner: :zbar_then_qreader,
+      python_command: :python3,
+      resolver: nil,
+      runner: CommandRunner.new,
+      qr_extractor: nil,
+      voucher_validator: VoucherValidator.new,
+      enrichment: true,
+      text_extractor: nil,
+      invoice_parser: nil,
+      reconciler: nil,
+      image_text_extractor: nil,
+      pdf_ocr_text_extractor: nil,
+      final_payload_builder: FinalPayloadBuilder.new
+    )
+      @configuration = Configuration.new(
+        strict: strict,
+        dependency_paths: dependency_paths,
+        page_range: page_range,
+        resolution: resolution,
+        multiple_qr: multiple_qr,
+        qr_scanner: qr_scanner,
+        python_command: python_command,
+        enrichment: enrichment
+      )
+
+      @resolver =
+        resolver ||
+        Dependencies::Resolver.new(
+          custom_paths: @configuration.dependency_paths
+        )
+
+      @runner = runner
+      @voucher_validator = voucher_validator
+      @text_extractor =
+        text_extractor ||
+        Pdf::TextExtractor.new(
+          resolver: @resolver,
+          runner: @runner
+        )
+
+      @invoice_parser =
+        invoice_parser ||
+        Text::InvoiceParser.new
+
+      @reconciler =
+        reconciler ||
+        Validation::Reconciler.new
+
+      @qr_extractor =
+        qr_extractor ||
+        QrExtractor.new(
+          resolver: @resolver,
+          runner: @runner,
+          page_range: effective_page_range,
+          resolution: @configuration.resolution,
+          multiple_qr: @configuration.multiple_qr,
+          qr_scanner: @configuration.qr_scanner,
+          python_command: @configuration.python_command
+        )
+
+      @image_text_extractor =
+        image_text_extractor ||
+        Ocr::RapidocrTextExtractor.new(
+          resolver: @resolver,
+          runner: @runner,
+          python_command: @configuration.python_command
+        )
+
+      @pdf_ocr_text_extractor =
+        pdf_ocr_text_extractor ||
+        Pdf::OcrTextExtractor.new(
+          renderer: Pdf::Renderer.new(
+            resolver: @resolver,
+            runner: @runner
+          ),
+          image_text_extractor: @image_text_extractor,
+          resolution: @configuration.resolution
+        )
+
+      @final_payload_builder = final_payload_builder
+    end
+
+    def extract(file_path)
+      validate_file!(file_path)
+
+      qr_result = @qr_extractor.extract(file_path)
+      voucher, errors = build_voucher_and_errors(qr_result)
+
+      return gated_failure(file_path, qr_result, voucher, errors) if errors.any?(&:error?)
+
+      text = extract_text(file_path)
+      unless text[:extracted]
+        diagnostics = text_warning_records(text)
+
+        return Result.new(
+          source: {path: file_path},
+          qr: qr_result,
+          voucher: voucher,
+          text: text,
+          enrichment: {},
+          validation: {
+            status: diagnostics.empty? ? "ok" : "warning",
+            comparisons: []
+          },
+          errors: diagnostics,
+          metadata: {}
+        )
+      end
+      parsed = @invoice_parser.parse(
+        raw: text[:raw],
+        normalized: text[:normalized],
+        voucher: voucher[:normalized]
+      )
+
+      validation = @reconciler.call(
+        voucher: voucher[:normalized],
+        enrichment: parsed[:enrichment],
+        parsing_warnings: parsed[:diagnostics]
+      )
+      Result.new(
+        source: {path: file_path},
+        qr: qr_result,
+        voucher: voucher,
+        text: text,
+        enrichment: parsed[:enrichment],
+        validation: validation,
+        errors: parsed[:diagnostics],
+        metadata: {},
+        final: @final_payload_builder.build(
+          qr_result: qr_result,
+          voucher: voucher,
+          enrichment: parsed[:enrichment]
+        )
+      )
+    rescue Error => e
+      raise if @configuration.strict?
+
+      failure_result(file_path, e)
+    end
+
+    def gated_failure(file_path, qr_result, voucher, errors)
+      raise_strict_error!(errors.first) if @configuration.strict?
+
+      Result.new(
+        source: {path: file_path},
+        qr: qr_result,
+        voucher: voucher,
+        text: {},
+        enrichment: {},
+        validation: {status: "error", comparisons: []},
+        errors: errors,
+        metadata: {}
+      )
+    end
+
+    private
+
+    def validate_file!(file_path)
+      unless File.file?(file_path) && File.readable?(file_path)
+        raise Errors::UnreadableFile,
+          "File not found or unreadable: #{file_path}"
+      end
+    end
+
+    def build_voucher_and_errors(qr_result)
+      unless qr_result[:found]
+        return [
+          nil,
+          qr_error_records(qr_result)
+        ]
+      end
+
+      original = qr_result[:payload]
+      normalized = @voucher_validator.validate_and_normalize(original)
+
+      [
+        {
+          original: original,
+          normalized: normalized
+        },
+        []
+      ]
+    rescue Errors::InvalidVoucherSchema => e
+      [
+        {
+          original: defined?(original) ? original : nil,
+          normalized: {}
+        },
+        [
+          ErrorRecord.new(
+            code: "invalid_voucher_schema",
+            message: e.message,
+            component: "voucher"
+          )
+        ]
+      ]
+    end
+
+    def failure_result(file_path, error)
+      Result.new(
+        source: {
+          path: file_path
+        },
+        qr: {},
+        voucher: nil,
+        text: {},
+        enrichment: {},
+        validation: {},
+        errors: [
+          error_record_from_exception(error)
+        ],
+        metadata: {}
+      )
+    end
+
+    def qr_error_records(qr_result)
+      qr_errors = Array(qr_result[:errors])
+
+      return [default_qr_not_found_error] if qr_errors.empty?
+
+      qr_errors.map do |error|
+        ErrorRecord.new(
+          code: error[:code],
+          message: error[:message],
+          component: error[:component],
+          details: error[:details] || {}
+        )
+      end
+    end
+
+    def default_qr_not_found_error
+      ErrorRecord.new(
+        code: "qr_not_found",
+        message: "No valid ARCA QR payload was found",
+        component: "qr"
+      )
+    end
+
+    def error_record_from_exception(error)
+      case error
+      when Errors::UnreadableFile
+        ErrorRecord.new(
+          code: "unreadable_file",
+          message: error.message,
+          component: "source"
+        )
+      when Errors::MissingDependency
+        ErrorRecord.new(
+          code: "missing_dependency",
+          message: error.message,
+          component: "dependencies",
+          details: {
+            missing: error.missing
+          }
+        )
+      when Errors::UnsupportedFileType
+        ErrorRecord.new(
+          code: "unsupported_file_type",
+          message: error.message,
+          component: "source"
+        )
+      else
+        ErrorRecord.new(
+          code: "extraction_error",
+          message: error.message,
+          component: "extractor"
+        )
+      end
+    end
+
+    def raise_strict_error!(error_record)
+      case error_record.code
+      when "qr_not_found"
+        raise Errors::QrNotFound, error_record.message
+      when "multiple_qr_found"
+        raise Errors::MultipleQrFound, error_record.message
+      when "invalid_voucher_schema"
+        raise Errors::InvalidVoucherSchema, error_record.message
+      else
+        raise Error, error_record.message
+      end
+    end
+
+    def extract_text(file_path)
+      return disabled_text_result unless @configuration.enrichment?
+
+      if pdf?(file_path)
+        pdf_text = @text_extractor.extract(
+          file_path,
+          page_range: effective_page_range
+        )
+
+        return pdf_text if pdf_text[:extracted]
+
+        empty_text = Array(pdf_text[:warnings]).any? do |warning|
+          warning[:code] == "pdf_text_empty"
+        end
+
+        return pdf_text unless empty_text
+
+        @pdf_ocr_text_extractor.extract(
+          file_path,
+          page_range: effective_page_range
+        )
+      else
+        @image_text_extractor.extract(file_path)
+      end
+    end
+
+    def disabled_text_result
+      {
+        extracted: false,
+        source: nil,
+        raw: "",
+        normalized: "",
+        pages: nil,
+        warnings: [
+          {
+            code: "enrichment_disabled",
+            message: "Text extraction is disabled",
+            component: "text"
+          }
+        ]
+      }
+    end
+
+    def not_applicable_text_result
+      {
+        extracted: false,
+        source: nil,
+        raw: "",
+        normalized: "",
+        pages: nil,
+        warnings: []
+      }
+    end
+
+    def pdf?(file_path)
+      File.extname(file_path).downcase == ".pdf"
+    end
+
+    def text_warning_records(text)
+      Array(text[:warnings]).map do |warning|
+        ErrorRecord.new(
+          code: warning[:code],
+          message: warning[:message],
+          severity: "warning",
+          component: warning[:component] || "text",
+          details: warning[:details] || {}
+        )
+      end
+    end
+
+    def effective_page_range
+      @configuration.page_range || 1
+    end
+  end
+end

data/lib/invoice_extractor_arca/final_payload_builder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module InvoiceExtractorArca
+  class FinalPayloadBuilder
+    def build(qr_result:, voucher:, enrichment:)
+      {
+        qr_payload: qr_result[:payload] || {},
+        normalized: normalized_fields(voucher, enrichment),
+        enrichment: serialize_enrichment(enrichment)
+      }
+    end
+
+    private
+
+    def normalized_fields(voucher, enrichment)
+      qr_fields = voucher&.dig(:normalized) || {}
+
+      enrichment_fields =
+        enrichment.each_with_object({}) do |(name, field), result|
+          next if name == :service_rows
+          next unless field.is_a?(Hash)
+
+          result[name] = field[:normalized]
+        end
+
+      # QR values are authoritative when names overlap.
+      enrichment_fields.merge(qr_fields)
+        .merge(
+          service_rows: normalized_service_rows(
+            enrichment[:service_rows]
+          )
+        )
+    end
+
+    def normalized_service_rows(rows)
+      Array(rows).map do |row|
+        row.each_with_object({}) do |(name, field), result|
+          result[name] =
+            if field.is_a?(Hash)
+              field[:normalized]
+            else
+              field
+            end
+        end
+      end
+    end
+
+    def serialize_enrichment(enrichment)
+      enrichment.each_with_object({}) do |(name, value), result|
+        result[name] =
+          if name == :service_rows
+            Array(value)
+          elsif value.is_a?(Hash)
+            {
+              raw: value[:raw],
+              normalized: value[:normalized],
+              source: value[:source],
+              method: value[:method],
+              confidence: value[:confidence]
+            }.compact
+          else
+            value
+          end
+      end
+    end
+  end
+end