facturx 0.2.0 → 1.1.0

data/lib/facturx/reader/term_reader.rb

@@ -28,14 +28,13 @@ module Facturx
         materialize(term, selected, cardinality)
       end
 
-      def group_nodes(id, context: @document, base_xpath: nil, &)
+      def group_nodes(id, context: @document, base_xpath: nil, collapse_if: nil, &)
         group = active_group(id)
         return [].freeze unless group
 
-        nodes = context.xpath(relative_xpath(group.xpath, base_xpath), NAMESPACES).to_a
-        nodes.select!(&) if block_given?
+        nodes = select_group_nodes(group, context, base_xpath, &)
         cardinality = group.cardinalities.fetch(@profile.id)
-        diagnose_cardinality(group, nodes, cardinality)
+        diagnose_cardinality(group, cardinality_nodes(nodes, collapse_if), cardinality)
         nodes.each { |node| mark(node) }
         nodes.freeze
       end
@@ -71,6 +70,15 @@ module Facturx
 
       private
 
+      def select_group_nodes(group, context, base_xpath, &filter)
+        nodes = context.xpath(relative_xpath(group.xpath, base_xpath), NAMESPACES).to_a
+        filter ? nodes.select(&filter) : nodes
+      end
+
+      def cardinality_nodes(nodes, collapse_if)
+        collapse_if&.call(nodes) ? [nodes.first] : nodes
+      end
+
       def active_term(id)
         term = @registry.fetch(id)
         term if term.cardinalities.key?(@profile.id)

data/lib/facturx/reader.rb

@@ -9,17 +9,13 @@ require_relative 'reading'
 require_relative 'source_reader'
 require_relative 'terms'
 require_relative 'xml/parser'
+require_relative 'xml/namespaces'
 require_relative 'xml/profile_detector'
 
 module Facturx
   class Reader
-    CII_NAMESPACE = 'urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100'
-    NAMESPACES = {
-      'qdt' => 'urn:un:unece:uncefact:data:standard:QualifiedDataType:100',
-      'ram' => 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100',
-      'rsm' => CII_NAMESPACE,
-      'udt' => 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100'
-    }.freeze
+    CII_NAMESPACE = Xml::Namespaces::CII
+    NAMESPACES = Xml::Namespaces::MAP
     UNKNOWN_PROFILE_POLICIES = %i[fallback raise].freeze
 
     COLLABORATORS = %i[profile_resolver registry coercer profiles].freeze

data/lib/facturx/source_reader.rb

@@ -13,7 +13,7 @@ module Facturx
 
     def call(source)
       unless source.is_a?(String)
-        raise InvalidXmlError.new('Source must be provided as a byte String', input_class: source.class.name)
+        raise InvalidSourceError.new('Source must be provided as a byte String', input_class: source.class.name)
       end
 
       return Result.new(xml: source, source_type: :xml) unless pdf?(source)

data/lib/facturx/validation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'model/immutable'
+
+module Facturx
+  module Validation
+    LAYERS = %i[syntax profile document xsd].freeze
+    SEVERITIES = %i[error warning].freeze
+    ISSUE_DEFAULTS = {
+      severity: :error,
+      term_id: nil,
+      group_id: nil,
+      path: nil,
+      line: nil,
+      column: nil,
+      details: {}
+    }.freeze
+    private_constant :LAYERS, :SEVERITIES, :ISSUE_DEFAULTS
+
+    Issue = Data.define(:code, :message, :layer, :severity, :term_id, :group_id, :path, :line, :column, :details) do
+      include Model::ValidatedWith
+
+      def initialize(**attributes)
+        Model.validate_attributes!(self.class.members, attributes)
+        attributes.fetch_values(:code, :message, :layer)
+        values = ISSUE_DEFAULTS.merge(attributes)
+        validate_values!(values)
+
+        super(**values.transform_values { |value| Model.copy_and_freeze(value) })
+      end
+
+      private
+
+      def validate_values!(values)
+        unless LAYERS.include?(values[:layer])
+          raise ArgumentError, "Unknown validation layer: #{values[:layer].inspect}"
+        end
+        unless SEVERITIES.include?(values[:severity])
+          raise ArgumentError, "Unknown validation severity: #{values[:severity].inspect}"
+        end
+        raise TypeError, 'details must be a Hash' unless values[:details].is_a?(Hash)
+      end
+    end
+
+    Report = Data.define(:profile, :issues) do
+      include Model::ValidatedWith
+
+      def initialize(profile: nil, issues: [])
+        raise TypeError, 'issues must be an Array' unless issues.is_a?(Array)
+        raise TypeError, 'issues must contain validation issues' unless issues.all?(Issue)
+
+        super(profile: Model.copy_and_freeze(profile), issues: Model.copy_and_freeze(issues))
+      end
+
+      def valid? = issues.none? { |issue| issue.severity == :error }
+
+      def invalid? = !valid?
+    end
+  end
+end

data/lib/facturx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Facturx
-  VERSION = '0.2.0'
+  VERSION = '1.1.0'
 end

data/lib/facturx/writer/context.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require_relative '../xml/namespaces'
+
+module Facturx
+  class Writer
+    class Context
+      attr_reader :document, :profile, :tracker, :xml, :root
+
+      def initialize(document:, profile:, tracker:)
+        @document = document
+        @profile = profile
+        @tracker = tracker
+        @xml = Nokogiri::XML::Document.new
+        @xml.encoding = 'UTF-8'
+        @root = namespaced_node('rsm', 'CrossIndustryInvoice')
+        Xml::Namespaces::MAP.each { |prefix, uri| @root.add_namespace_definition(prefix, uri) }
+        @root.namespace = namespace('rsm')
+        @xml.root = @root
+      end
+
+      def transaction
+        @transaction ||= element(@root, 'rsm:SupplyChainTradeTransaction')
+      end
+
+      def element(parent, qualified_name, text: nil, attributes: {})
+        prefix, name = qualified_name.split(':', 2)
+        node = namespaced_node(prefix, name)
+        attributes.each { |attribute, value| node[attribute.to_s] = value }
+        node.content = text unless text.nil?
+        parent.add_child(node)
+        node
+      end
+
+      def to_xml
+        @xml.to_xml(encoding: 'UTF-8')
+      end
+
+      private
+
+      def namespaced_node(prefix, name)
+        node = Nokogiri::XML::Node.new(name, @xml)
+        node.namespace = namespace(prefix) if @root
+        node
+      end
+
+      def namespace(prefix)
+        @root&.namespace_definitions&.find { |item| item.prefix == prefix }
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../error'
+require_relative '../format'
+require_relative '../terms'
+require_relative 'stage_support/contact_details'
+require_relative 'stage_support/emission'
+require_relative 'stage_support/identifiers'
+require_relative 'stage_support/structure'
+
+module Facturx
+  class Writer
+    class Stage
+      include StageSupport::Emission
+      include StageSupport::Structure
+      include StageSupport::ContactDetails
+      include StageSupport::Identifiers
+
+      class << self
+        def term_ids(*ids)
+          @term_ids = ids.map(&:to_s).freeze unless ids.empty?
+          @term_ids || [].freeze
+        end
+      end
+
+      def initialize(context)
+        @context = context
+      end
+
+      private
+
+      attr_reader :context
+
+      def document
+        context.document
+      end
+
+      def profile
+        context.profile
+      end
+
+      def tracker
+        context.tracker
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/contact_details.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module ContactDetails
+        ADDRESS_ELEMENTS = {
+          postcode: 'ram:PostcodeCode',
+          line_one: 'ram:LineOne',
+          line_two: 'ram:LineTwo',
+          line_three: 'ram:LineThree',
+          city: 'ram:CityName',
+          country_code: 'ram:CountryID',
+          country_subdivision: 'ram:CountrySubDivisionName'
+        }.freeze
+
+        private
+
+        def emit_date(parent, id, value, wrapper:, value_element: 'udt:DateTimeString')
+          unless value
+            emit(id, nil, element: value_element, parent:)
+            return
+          end
+
+          container(parent, wrapper) do |node|
+            emit(id, value, element: value_element, parent: node, attributes: { 'format' => '102' })
+          end
+        end
+
+        def emit_address(parent, address, group_id, ids)
+          within_group(group_id, address, element: 'ram:PostalTradeAddress', parent:) do |node, item|
+            ADDRESS_ELEMENTS.each do |attribute, element|
+              emit(ids.fetch(attribute), item.public_send(attribute), element:, parent: node)
+            end
+          end
+        end
+
+        def emit_contact(parent, contact, group_id, ids)
+          within_group(group_id, contact, element: 'ram:DefinedTradeContact', parent:) do |node, item|
+            emit(ids.fetch(:name), item.name, element: 'ram:PersonName', parent: node)
+            communication(node, ids.fetch(:telephone), item.telephone,
+                          'ram:TelephoneUniversalCommunication', 'ram:CompleteNumber')
+            communication(node, ids.fetch(:email), item.email, 'ram:EmailURIUniversalCommunication', 'ram:URIID')
+          end
+        end
+
+        def communication(parent, id, value, wrapper, element)
+          if value
+            container(parent, wrapper) { |node| emit(id, value, element:, parent: node) }
+          else
+            emit(id, nil, element:, parent:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/emission.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module Emission
+        private
+
+        def emit(id, value, **options)
+          term = Terms.fetch(id)
+          values = present_values(value)
+          return [] unless options.fetch(:group_present, true)
+
+          accepted = tracker.observe_term?(term, values:, path: term.xpath)
+          return [] unless accepted
+
+          values.filter_map { |item| emit_value(term, item, options) }
+        end
+
+        def emit_attribute(id, value, **options)
+          term = Terms.fetch(id)
+          values = present_values(value)
+          group_present = options.fetch(:group_present, !options.fetch(:node).nil?)
+          return unrepresentable(id, 'Qualifier requires its carrier') if !group_present && values.any?
+          return unless group_present
+
+          accepted = tracker.observe_term?(term, values:, path: term.xpath)
+          return unless accepted
+
+          emit_attribute_value(term, values, options)
+        end
+
+        def observe?(id, value, group_present: true)
+          return false unless group_present
+
+          term = Terms.fetch(id)
+          tracker.observe_term?(term, values: present_values(value), path: term.xpath)
+        end
+
+        def unrepresentable(id, message)
+          term = Terms.fetch(id)
+          tracker.invalid_term(term, error: FormattingError.new(message, path: term.xpath), path: term.xpath)
+        end
+
+        def present_values(value)
+          (value.is_a?(Array) ? value : [value]).compact
+        end
+
+        def format(value, term)
+          Format.call(value, term:)
+        rescue FormattingError => e
+          tracker.invalid_term(term, error: e, path: term.xpath)
+          nil
+        end
+
+        def emit_value(term, value, options)
+          formatted = format(value, term)
+          return unless formatted
+
+          context.element(
+            options.fetch(:parent),
+            options.fetch(:element),
+            text: formatted,
+            attributes: options.fetch(:attributes, {})
+          )
+        end
+
+        def emit_attribute_value(term, values, options)
+          node = options.fetch(:node)
+          return unless node && values.one?
+
+          formatted = format(values.first, term)
+          node[options.fetch(:attribute)] = formatted if formatted
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/identifiers.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module Identifiers
+        private
+
+        def emit_compound_identifier(parent, identifier, **options)
+          value_id = options.fetch(:value_id)
+          value = identifier&.value
+          node = emit(value_id, value, element: options.fetch(:element), parent:).first
+          emit_identifier_scheme(node, identifier, options)
+          node
+        end
+
+        def emit_party_identifiers(parent, identifiers, value_id, scheme_id)
+          items = Array(identifiers)
+          local, global = items.partition { |item| item.scheme_id.nil? }
+          missing, global = global.partition { |item| item.value.to_s.strip.empty? }
+          emit_global_identifiers(parent, missing, value_id, scheme_id)
+
+          return unless observe?(value_id, items.map(&:value))
+
+          emit_local_identifiers(parent, local, value_id)
+          emit_global_identifiers(parent, global, value_id, scheme_id)
+        end
+
+        def format_identifier_value(id, value)
+          return if value.nil?
+
+          format(value, Terms.fetch(id))
+        end
+
+        def emit_tax_registration(parent, id, identifier, scheme)
+          report_unrepresentable_identifier_scheme(id, identifier, represented_scheme: scheme)
+          value = identifier&.value
+          unless value
+            observe?(id, nil)
+            return
+          end
+
+          container(parent, 'ram:SpecifiedTaxRegistration') do |node|
+            emit(id, value, element: 'ram:ID', parent: node, attributes: { 'schemeID' => scheme })
+          end
+        end
+
+        def emit_document_reference(parent, id, reference, element, represented_attributes: [])
+          unless reference
+            observe?(id, nil)
+            return
+          end
+
+          represented = [:id, *represented_attributes]
+          report_unrepresentable_reference_attributes(id, reference, represented_attributes: represented)
+
+          container(parent, element) do |node|
+            emit(id, reference.id, element: 'ram:IssuerAssignedID', parent: node)
+          end
+        end
+
+        def emit_invoiced_object(parent, identifier, value_id, scheme_id)
+          unless identifier&.value
+            observe?(value_id, nil)
+            report_unrepresentable_identifier_scheme(scheme_id, identifier)
+            return
+          end
+
+          container(parent, 'ram:AdditionalReferencedDocument') do |node|
+            emit(value_id, identifier.value, element: 'ram:IssuerAssignedID', parent: node)
+            technical(node, 'ram:TypeCode', '130')
+            emit(scheme_id, identifier.scheme_id, element: 'ram:ReferenceTypeCode', parent: node)
+          end
+        end
+
+        def report_unrepresentable_reference_attributes(id, reference, represented_attributes: [])
+          %i[id line_id name issue_date].each do |attribute|
+            next unless reference.public_send(attribute) && !represented_attributes.include?(attribute)
+
+            unrepresentable(id, "Document reference #{attribute} cannot be represented")
+          end
+        end
+
+        def emit_identifier_value(id, identifier, element, parent)
+          report_unrepresentable_identifier_scheme(id, identifier)
+          emit(id, identifier&.value, element:, parent:)
+        end
+
+        def report_unrepresentable_identifier_scheme(id, identifier, represented_scheme: nil)
+          scheme_id = identifier&.scheme_id
+          return unless scheme_id && scheme_id != represented_scheme
+
+          unrepresentable(id, 'Identifier scheme cannot be represented')
+        end
+
+        def emit_identifier_scheme(node, identifier, options)
+          scheme_id = options[:scheme_id]
+          return unless scheme_id
+
+          emit_attribute(
+            scheme_id,
+            identifier&.scheme_id,
+            node:,
+            attribute: options.fetch(:scheme_attribute, 'schemeID'),
+            group_present: !node.nil?
+          )
+        end
+
+        def emit_local_identifiers(parent, identifiers, value_id)
+          identifiers.each do |item|
+            technical(parent, 'ram:ID', format_identifier_value(value_id, item.value))
+          end
+        end
+
+        def emit_global_identifiers(parent, identifiers, value_id, scheme_id)
+          identifiers.each do |item|
+            if item.value.to_s.strip.empty?
+              unrepresentable(value_id, 'Global identifier requires a value')
+              next
+            end
+
+            node = technical(parent, 'ram:GlobalID', format_identifier_value(value_id, item.value))
+            emit_attribute(scheme_id, item.scheme_id, node:, attribute: 'schemeID', group_present: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stage_support/structure.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module StageSupport
+      module Structure
+        private
+
+        def within_group(id, value, element:, parent:, represented_attributes: [])
+          group = Terms.group(id)
+          values = present_values(value)
+          accepted = tracker.observe_group?(group, count: values.size, path: group.xpath)
+          return unless accepted
+
+          values.each do |item|
+            write_group_item(group, item, element, parent, represented_attributes) { |node| yield(node, item) }
+          end
+        end
+
+        def each_group(id, values, element:, parent:, represented_attributes: [], &)
+          within_group(id, Array(values), element:, parent:, represented_attributes:, &)
+        end
+
+        def write_group_item(group, item, element, parent, represented_attributes)
+          if group.attribute
+            report_unrepresentable_attributes(group.id, item, model: group.model,
+                                                              represented_attributes:)
+          end
+          node = context.element(parent, element)
+          yield node
+          remove_if_empty(node)
+        end
+
+        def technical(parent, element, value, default: nil)
+          text = value.to_s
+          text = default.to_s if text.strip.empty?
+          return if text.strip.empty?
+
+          context.element(parent, element, text:)
+        end
+
+        def container(parent, element)
+          node = context.element(parent, element)
+          yield node
+          remove_if_empty(node)
+          node
+        end
+
+        def remove_if_empty(node)
+          node.remove if node.element_children.empty? && node.text.empty? && node.attribute_nodes.empty?
+        end
+
+        def report_unrepresentable_attributes(group_id, item, model: model_for(item), represented_attributes: [])
+          return unless item.is_a?(Data) && model_for(item) == model
+
+          group = Terms.group(group_id)
+          item.members.each do |attribute|
+            value = item.public_send(attribute)
+            next unless unrepresentable_attribute?(group, model, attribute, value, represented_attributes)
+
+            tracker.unrepresentable_attribute(group, model:, attribute:)
+          end
+        end
+
+        def report_unrepresentable_attribute(group_id, model:, attribute:)
+          tracker.unrepresentable_attribute(Terms.group(group_id), model:, attribute:)
+        end
+
+        def attribute_supported_in_group?(group, model, attribute)
+          Terms.all.any? { |term| term.group_id == group.id && term.model == model && term.attribute == attribute }
+        end
+
+        def unrepresentable_attribute?(group, model, attribute, value, represented_attributes)
+          populated?(value) && !represented_attributes.include?(attribute) &&
+            !attribute_supported_in_group?(group, model, attribute)
+        end
+
+        def populated?(value)
+          !value.nil? && (!value.respond_to?(:empty?) || !value.empty?)
+        end
+
+        def model_for(item)
+          item.class.name.split('::').last.gsub(/([a-z\\d])([A-Z])/, '\\1_\\2').downcase.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/document_context.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class DocumentContext < Stage
+        term_ids 'BT-23', 'BT-24'
+
+        def call
+          within_group('BG-2', document, element: 'rsm:ExchangedDocumentContext', parent: context.root,
+                                         represented_attributes: [:vat_point_date_code]) do |node,|
+            emit_context_parameter(node, 'BT-23', document.business_process,
+                                   'ram:BusinessProcessSpecifiedDocumentContextParameter')
+            guideline = document.guideline_urn || profile.guideline_urn
+            emit_context_parameter(node, 'BT-24', guideline, 'ram:GuidelineSpecifiedDocumentContextParameter')
+          end
+        end
+
+        private
+
+        def emit_context_parameter(parent, id, value, element)
+          if value
+            container(parent, element) { |node| emit(id, value, element: 'ram:ID', parent: node) }
+          else
+            emit(id, nil, element: 'ram:ID', parent: parent)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/exchanged_document.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class ExchangedDocument < Stage
+        term_ids 'BT-1', 'BT-3', 'BT-2', 'BT-22', 'BT-21'
+
+        def call
+          node = context.element(context.root, 'rsm:ExchangedDocument')
+          emit('BT-1', document.invoice_number, element: 'ram:ID', parent: node)
+          emit('BT-3', document.type_code, element: 'ram:TypeCode', parent: node)
+          issue_date(node)
+          notes(node)
+        end
+
+        private
+
+        def notes(parent)
+          each_group('BG-1', document.notes, element: 'ram:IncludedNote', parent:) do |note_node, note|
+            emit('BT-22', note.content, element: 'ram:Content', parent: note_node)
+            emit('BT-21', note.subject_code, element: 'ram:SubjectCode', parent: note_node)
+          end
+        end
+
+        def issue_date(parent)
+          emit_date(parent, 'BT-2', document.issue_date, wrapper: 'ram:IssueDateTime')
+        end
+      end
+    end
+  end
+end