facturx 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61ac3e80ab256d20b48527e6b92bccd30fcc6f0b7d1b87dec452161fd9e916fb
-  data.tar.gz: 35227d6b843d4c7f51608c2d149b4ce456ca854b16a14ed11317dab0ba2f2cfe
+  metadata.gz: 10cd4d86db6d643606dbd85da9ced31d20e884249505e8a608ebb864f9a2f2ef
+  data.tar.gz: 3e0665c807043cdca83550452ab2b1e3ca7d40b759105eea8856916a316576fd
 SHA512:
-  metadata.gz: aa5602b1058a4e5cd06821ea7995d761983b9ddf6cb736e3bcc46e8473230baaf6f215b8f78034f633f19223072b24ce6e474466f5a534801e89516e6d949854
-  data.tar.gz: 3f9504f7f0c04245bd50948d38a1608f1accc18c5bda8dc953229ef60ac4e7cd1071aa15bef81172007e41d6c4eae76cbeaa4999d67d2fb80e52fe9dd00db4da
+  metadata.gz: 0cf6cb2b75adb6a668a5746420ee82177aada0c87d9d40bd625387a59d1409b63ef53916df3480aa7adaf539b59c99fb635667134e3cefcbd66590f1a19aeecd
+  data.tar.gz: 3e7715e0181e11b9b0589ab85da8194e692647fcb4be0d42d177968584d0cc1f1e2114a782e8d533c7c5a2fbac0943bc2bd4964e59633773c9dd864e5a42cee4

data/CHANGELOG.md

@@ -4,13 +4,40 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-09-13
+
+### Add
+
+- Add immutable invoice construction through a typed nested DSL.
+- Add aggregated document conformance validation for all five built-in profiles.
+- Add profile-specific Factur-X XML generation and PDF generation from typed documents.
+- Add strict RBI signatures for the public models, builders, reports, errors, and facades.
+- Add maintainer verification of term membership and cardinalities against pinned official workbooks.
+
+### Fix
+
+- Fix partial or unrepresentable values so supplied data is rejected instead of silently discarded.
+- Fix repeated credit transfers and discriminated references across semantic round trips.
+- Fix MINIMUM accounting-currency tax totals without emitting the forbidden tax currency term.
+- Fix invalid profile objects to raise the documented typed error.
+
+## [0.2.0] - 2026-09-12
+
+### Add
+
+- Read XML or PDF bytes into an immutable, typed EN16931 document model with structured diagnostics.
+- Map the complete EN16931 semantic term set and the MINIMUM, BASIC WL, and BASIC subsets.
+- Verify semantic mapping provenance and official examples with the maintainer reference task.
+
 ## [0.1.0] - 2026-09-11
 
-### Added
+### Add
 
 - Validate Factur-X 1.09.2 XML against its profile XSD.
 - Compose PDF/A-3b Factur-X documents with Ghostscript.
 - Extract embedded Factur-X XML from PDF documents.
 
-[Unreleased]: https://github.com/AdVitam/facturx/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/AdVitam/facturx/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/AdVitam/facturx/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/AdVitam/facturx/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/AdVitam/facturx/releases/tag/v0.1.0

data/NOTICE.md

@@ -4,6 +4,8 @@
 
 The gem includes Factur-X 1.09.2 / ZUGFeRD 2.5.2 XSD validation artefacts. Their Apache License 2.0 text, provenance, RubyGems packaging adaptation, and file checksums are packaged under `lib/facturx/schema/`.
 
+The semantic term registry is derived from the official Factur-X 1.09.2 profile workbooks. The workbooks and examples are not redistributed; their expected paths and SHA-256 checksums are recorded in `Facturx::Terms::REFERENCE_FILES` for maintainer verification.
+
 ## Ghostscript
 
 PDF composition invokes a Ghostscript installation supplied by the user. Ghostscript, `zugferd.ps`, and ICC profiles are not part of this gem and remain governed by their respective licences.

data/README.md

@@ -1,6 +1,6 @@
 # facturx
 
-`facturx` validates Factur-X XML, creates PDF/A-3b Factur-X invoices from existing PDFs, and extracts their embedded XML.
+`facturx` builds, reads, and validates Factur-X XML, creates PDF/A-3b Factur-X invoices from existing PDFs, and extracts their embedded XML.
 
 The first release supports Factur-X 1.09.2 / ZUGFeRD 2.5.2 with the MINIMUM, BASIC WL, BASIC, EN 16931, and EXTENDED profiles.
 
@@ -26,20 +26,72 @@ require 'facturx'
 xml = File.binread('invoice.xml')
 pdf = File.binread('invoice.pdf')
 
-Facturx.verify_xml(xml: xml) # => true
+Facturx.verify_xml(xml: xml)
+
+reading = Facturx.read(xml)
+reading.document.invoice_number
+reading.document.totals.grand_total
+reading.diagnostics
 
 facturx_pdf = Facturx.attach(pdf: pdf, xml: xml)
 File.binwrite('invoice-facturx.pdf', facturx_pdf)
 
 embedded_xml = Facturx.extract_xml(pdf: facturx_pdf)
+pdf_reading = Facturx.read(facturx_pdf)
+```
+
+Build a typed document with the nested DSL, validate it without generating XML, or generate XML and attach it to an existing PDF:
+
+```ruby
+document = Facturx::Document.build(
+  invoice_number: 'INV-2026-0042',
+  type_code: '380',
+  issue_date: Date.new(2026, 9, 12),
+  currency: 'EUR'
+) do |invoice|
+  invoice.seller do |seller|
+    seller.name = 'Seller SAS'
+    seller.address(country_code: 'FR')
+  end
+  invoice.buyer(name: 'Buyer SAS')
+  invoice.totals(
+    tax_basis_total: BigDecimal('100.00'),
+    grand_total: BigDecimal('120.00'),
+    due_payable: BigDecimal('120.00')
+  )
+end
+
+report = Facturx.validate_document(document:, profile: :minimum)
+report.valid?
+
+xml = Facturx.build_xml(document:, profile: :minimum)
+facturx_pdf = Facturx.generate(pdf:, document:, profile: :minimum)
 ```
 
+`profile:` accepts one of `:minimum`, `:basic_wl`, `:basic`, `:en16931`, or `:extended`, as well as the corresponding canonical `Facturx::Profile`. When BT-24 is absent, the writer inserts the selected profile's guideline URN. A conflicting BT-24 is reported as a profile mismatch.
+
+`validate_document` returns an immutable report containing every conformance issue found. `build_xml` and `generate` raise `Facturx::ConformanceError` with that report when the document is invalid. Values are serialized from their declared semantic type; monetary values with more than two decimal places are rejected instead of being rounded implicitly. Generated XML is always checked against the selected profile's XSD.
+
 `verify_xml` infers the profile from BT-24 and validates the document against that profile's XSD. It returns `true` on success and raises a typed `Facturx::Error` on failure.
 
 `attach` always validates the XML first. It converts the input PDF to PDF/A-3b, embeds the original XML bytes as `factur-x.xml`, and verifies the resulting attachment and metadata. Signed and encrypted PDFs are rejected because rewriting them would invalidate their protection.
 
 `extract_xml` returns the embedded bytes without validating them. This allows callers to inspect non-conforming invoices received from third parties and explicitly call `verify_xml` when appropriate.
 
+`read` accepts either XML or PDF bytes and returns an immutable `Facturx::Reading`. Its `document` contains typed immutable values: dates are `Date`, decimals are `BigDecimal`, identifiers retain their schemes, and repeating groups are frozen arrays in XML order. `source` always contains the exact embedded XML bytes and `source_type` is either `:xml` or `:pdf`.
+
+Reading is intentionally tolerant and never performs implicit XSD validation. Missing, duplicate, empty, invalid, or unmapped values are reported through immutable diagnostics while usable fields remain accessible. Call `verify_xml` separately when strict structural validation is required.
+
+Unknown or missing BT-24 values fall back to the EN16931 intersection supported for EXTENDED documents and add a diagnostic. Pass `on_unknown_profile: :raise` to reject them instead:
+
+```ruby
+Facturx.read(xml, on_unknown_profile: :raise)
+```
+
+The semantic registry covers all 184 EN16931 business terms and the MINIMUM, BASIC WL, and BASIC subsets. EXTENDED-only fields remain available in `Reading#source` and are reported as unmapped until their model is added.
+
+Reading is not a fidelity round-trip. To reissue an incoming invoice, retain and reuse `Reading#source`; the writer cannot reproduce fields outside the semantic model.
+
 The byte-string API materializes PDF streams in memory. Process untrusted PDFs in a resource-limited worker; limiting only the input file size does not prevent amplification by a compressed embedded stream.
 
 ## Ghostscript discovery
@@ -56,9 +108,9 @@ The gem invokes Ghostscript as an external process. It does not distribute Ghost
 
 ## Validation scope
 
-Version 0.1 validates XML structure with the official XSDs. It does not yet run the Factur-X Schematron business rules. XSD validation alone must not be presented as complete semantic or regulatory validation.
+The gem validates generated documents against its EN16931 semantic registry and the official profile XSDs. It does not yet run the Factur-X Schematron business rules, calculate totals, or evaluate accounting consistency. These checks must not be presented as complete regulatory validation.
 
-The gem does not generate invoice XML or the visual invoice PDF, communicate with a PDP, or implement e-reporting.
+The gem does not generate the visual invoice PDF, communicate with a PDP, or implement e-reporting. EXTENDED-only fields are not generated until they are represented in the typed model.
 
 ## Development
 
@@ -70,6 +122,12 @@ bundle exec rspec
 bundle exec rake build
 ```
 
+Maintainers can verify the registry hashes, D22B element names, semantic diagnostics, official XML examples, and paired PDF attachments against an extracted upstream package:
+
+```bash
+FACTURX_REFERENCE_ROOT=/path/to/ZUGFeRD_2.5.2_EN bundle exec rake reference:verify
+```
+
 ## License
 
 The gem code is available under the MIT License. Bundled standard artefacts retain their respective upstream notices; see `NOTICE.md`.

data/lib/facturx/builders/association.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Facturx
+  module Builders
+    Association = Data.define(:model, :collection, :helper)
+    private_constant :Association
+  end
+end

data/lib/facturx/builders/base.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Facturx
+  module Builders
+    class Base
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      class << self
+        attr_reader :model, :associations
+
+        def configure(model, associations)
+          @model = model
+          @associations = associations
+          define_attribute_methods
+          self
+        end
+
+        def build(**attributes, &block)
+          builder = new(**attributes)
+          block&.call(builder)
+          builder.build
+        end
+
+        private
+
+        def define_attribute_methods
+          model.members.each do |attribute|
+            association = associations[attribute]
+            association ? define_association_methods(attribute, association) : define_scalar_methods(attribute)
+          end
+        end
+
+        def define_scalar_methods(attribute)
+          define_method(attribute) { @attributes[attribute] }
+          define_method(:"#{attribute}=") { |value| @attributes[attribute] = value }
+        end
+
+        def define_association_methods(attribute, association)
+          if association.collection
+            define_collection_helper(attribute, association)
+          else
+            define_singular_helper(attribute, association)
+          end
+          define_method(:"#{attribute}=") { |value| set_association(attribute, association, value) }
+        end
+
+        def define_singular_helper(attribute, association)
+          define_method(attribute) do |value = UNSET, **attributes, &block|
+            assign_association(attribute, association, value, attributes, block)
+          end
+        end
+
+        def define_collection_helper(attribute, association)
+          define_method(association.helper) do |value = UNSET, **attributes, &block|
+            append_association(attribute, association, value, attributes, block)
+          end
+          define_method(attribute) { @attributes.fetch(attribute, []).dup.freeze }
+        end
+      end
+
+      def initialize(**attributes)
+        unknown = attributes.keys - self.class.model.members
+        raise ArgumentError, "Unknown attributes: #{unknown.map(&:inspect).join(', ')}" unless unknown.empty?
+
+        @attributes = {}
+        attributes.each { |attribute, value| public_send(:"#{attribute}=", value) }
+      end
+
+      def build
+        self.class.model.new(**@attributes)
+      end
+
+      private
+
+      def assign_association(attribute, association, value, attributes, block)
+        if @attributes.key?(attribute)
+          raise ArgumentError,
+                "#{attribute} is already set; use #{attribute}= to replace it"
+        end
+
+        object = association_value(attribute, association, value, attributes, block)
+        @attributes[attribute] = object
+      end
+
+      def append_association(attribute, association, value, attributes, block)
+        object = association_value(association.helper, association, value, attributes, block)
+        (@attributes[attribute] ||= []) << object
+        object
+      end
+
+      def set_association(attribute, association, value)
+        if association.collection
+          set_collection(attribute, association, value)
+        else
+          validate_object!(attribute, association.model, value) unless value.nil?
+          @attributes[attribute] = value
+        end
+      end
+
+      def set_collection(attribute, association, value)
+        raise TypeError, "#{attribute} must be an Array" unless value.is_a?(Array)
+
+        value.each { |object| validate_object!(attribute, association.model, object) }
+        @attributes[attribute] = value.dup
+      end
+
+      def association_value(name, association, value, attributes, block)
+        forms = [!value.equal?(UNSET), !attributes.empty?, !block.nil?]
+        unless forms.one?
+          raise ArgumentError, "#{name} accepts exactly one of an object, keyword attributes, or a block"
+        end
+
+        return validate_object!(name, association.model, value) unless value.equal?(UNSET)
+
+        builder = Builders.for(association.model)
+        attributes.empty? ? builder.build(&block) : builder.build(**attributes)
+      end
+
+      def validate_object!(attribute, model, object)
+        unless object.instance_of?(model) && object.frozen?
+          raise TypeError, "#{attribute} must be an immutable #{model.name}"
+        end
+
+        object
+      end
+    end
+  end
+end

data/lib/facturx/builders/schema.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative 'association'
+
+module Facturx
+  module Builders
+    module Schema
+      module_function
+
+      def singular(model)
+        Association.new(model:, collection: false, helper: nil)
+      end
+
+      def collection(model, helper)
+        Association.new(model:, collection: true, helper:)
+      end
+
+      ASSOCIATIONS = {
+        Note => {},
+        Identifier => {},
+        Period => {},
+        Quantity => {},
+        Contact => {},
+        Address => {},
+        Party => {
+          identifiers: collection(Identifier, :identifier),
+          legal_registration: singular(Identifier),
+          address: singular(Address),
+          vat_identifier: singular(Identifier),
+          tax_identifier: singular(Identifier),
+          electronic_address: singular(Identifier),
+          contact: singular(Contact)
+        },
+        CreditTransfer => {
+          account_identifier: singular(Identifier),
+          provider_identifier: singular(Identifier)
+        },
+        PaymentCard => {},
+        DirectDebit => {
+          mandate_identifier: singular(Identifier),
+          creditor_identifier: singular(Identifier),
+          debtor_account_identifier: singular(Identifier)
+        },
+        PaymentInstructions => {
+          credit_transfers: collection(CreditTransfer, :credit_transfer),
+          payment_card: singular(PaymentCard),
+          direct_debit: singular(DirectDebit)
+        },
+        DocumentReference => {},
+        Delivery => {
+          location_identifier: singular(Identifier),
+          party: singular(Party)
+        },
+        SupportingDocument => {},
+        ProductAttribute => {},
+        ProductClassification => {},
+        Product => {
+          seller_identifier: singular(Identifier),
+          buyer_identifier: singular(Identifier),
+          global_identifier: singular(Identifier),
+          attributes: collection(ProductAttribute, :attribute),
+          classifications: collection(ProductClassification, :classification)
+        },
+        Price => {
+          basis_quantity: singular(Quantity)
+        },
+        TaxBreakdown => {},
+        AllowanceCharge => {
+          tax: singular(TaxBreakdown)
+        },
+        Totals => {},
+        Line => {
+          product: singular(Product),
+          quantity: singular(Quantity),
+          gross_price: singular(Price),
+          net_price: singular(Price),
+          tax: singular(TaxBreakdown),
+          period: singular(Period),
+          allowances: collection(AllowanceCharge, :allowance),
+          charges: collection(AllowanceCharge, :charge),
+          buyer_order_reference: singular(DocumentReference),
+          invoiced_object_identifier: singular(Identifier)
+        },
+        Document => {
+          project_reference: singular(DocumentReference),
+          contract_reference: singular(DocumentReference),
+          purchase_order_reference: singular(DocumentReference),
+          sales_order_reference: singular(DocumentReference),
+          receiving_advice_reference: singular(DocumentReference),
+          despatch_advice_reference: singular(DocumentReference),
+          tender_or_lot_reference: singular(DocumentReference),
+          invoiced_object_identifier: singular(Identifier),
+          seller: singular(Party),
+          buyer: singular(Party),
+          payee: singular(Party),
+          tax_representative: singular(Party),
+          delivery: singular(Delivery),
+          billing_period: singular(Period),
+          payment: singular(PaymentInstructions),
+          totals: singular(Totals),
+          notes: collection(Note, :note),
+          lines: collection(Line, :line),
+          tax_breakdowns: collection(TaxBreakdown, :tax_breakdown),
+          allowances: collection(AllowanceCharge, :allowance),
+          charges: collection(AllowanceCharge, :charge),
+          preceding_invoices: collection(DocumentReference, :preceding_invoice),
+          supporting_documents: collection(SupportingDocument, :supporting_document)
+        }
+      }.transform_values(&:freeze).freeze
+    end
+  end
+end

data/lib/facturx/builders.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'document'
+require_relative 'builders/schema'
+require_relative 'builders/base'
+
+module Facturx
+  module Builders
+    BUILDERS = Schema::ASSOCIATIONS.to_h do |model, associations|
+      name = :"#{model.name.delete_prefix('Facturx::')}Builder"
+      [model, const_set(name, Class.new(Base).configure(model, associations))]
+    end.freeze
+    private_constant :BUILDERS
+
+    module_function
+
+    def for(model)
+      BUILDERS.fetch(model)
+    end
+  end
+
+  Document.define_singleton_method(:build) do |**attributes, &block|
+    Builders::DocumentBuilder.build(**attributes, &block)
+  end
+end

data/lib/facturx/coerce.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'date'
+require_relative 'error'
+
+module Facturx
+  class CoercionError < Error; end
+
+  module Coerce
+    CONVERTERS = {
+      string: :string,
+      date_102: :formatted_date,
+      decimal: :decimal,
+      boolean: :boolean,
+      binary: :binary
+    }.freeze
+
+    module_function
+
+    def call(value, type:, scale: nil, **context)
+      return if value.nil?
+
+      converter = CONVERTERS[type]
+      raise ArgumentError, "Unsupported coercion type: #{type.inspect}" unless converter
+
+      begin
+        public_send(converter, value, context)
+      rescue ArgumentError, TypeError => e
+        raise CoercionError.new('Value cannot be coerced', value:, type:, scale:, **context), cause: e
+      end
+    end
+
+    def string(value, _context = nil)
+      raise TypeError, 'expected a String' unless value.is_a?(String)
+
+      value.dup.freeze
+    end
+
+    def decimal(value, _context = nil)
+      raise TypeError, 'Float values are not supported' if value.is_a?(Float)
+      return value if value.is_a?(BigDecimal)
+
+      decimal = BigDecimal(value.to_s, exception: true)
+      raise ArgumentError, 'decimal must be finite' unless decimal.finite?
+
+      decimal
+    end
+
+    def formatted_date(value, _context = nil)
+      return value.dup.freeze if value.is_a?(Date)
+
+      text = string(value)
+      raise ArgumentError, 'date must use format 102' unless text.match?(/\A\d{8}\z/)
+
+      Date.strptime(text, '%Y%m%d').freeze
+    end
+
+    def boolean(value, _context = nil)
+      return value if [true, false].include?(value)
+
+      case string(value)
+      when 'true', '1' then true
+      when 'false', '0' then false
+      else raise ArgumentError, 'boolean must be true, false, 1, or 0'
+      end
+    end
+
+    def binary(value, _context = nil)
+      encoded = string(value).delete(" \t\r\n")
+      encoded.unpack1('m0').force_encoding(Encoding::BINARY).freeze
+    end
+  end
+end

data/lib/facturx/conformance.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+require_relative 'model/immutable'
+
+module Facturx
+  module Conformance
+    Issue = Data.define(:code, :message, :term_id, :group_id, :path, :details) do
+      include Model::ValidatedWith
+
+      def initialize(**attributes)
+        Model.validate_attributes!(self.class.members, attributes)
+        attributes.fetch_values(:code, :message)
+        values = { term_id: nil, group_id: nil, path: nil, details: {} }.merge(attributes)
+        raise TypeError, 'details must be a Hash' unless values[:details].is_a?(Hash)
+
+        super(**values.transform_values { |value| Model.copy_and_freeze(value) })
+      end
+    end
+
+    Report = Data.define(:profile, :issues) do
+      include Model::ValidatedWith
+
+      def initialize(profile:, issues: [])
+        raise TypeError, 'issues must be an Array' unless issues.is_a?(Array)
+
+        super(profile: Model.copy_and_freeze(profile), issues: Model.copy_and_freeze(issues))
+      end
+
+      def valid? = issues.empty?
+
+      def invalid? = !valid?
+    end
+
+    module Tracking
+      private
+
+      def definition_observed?(definition, count, path)
+        cardinality = definition.cardinalities[profile.id]
+        return forbidden?(definition, count, path) unless cardinality
+
+        missing(definition, path, cardinality) if count.zero? && required?(cardinality)
+        invalid_cardinality(definition, count, path, cardinality) if count > 1 && !repeated?(cardinality)
+        count.positive?
+      end
+
+      def forbidden?(definition, count, path)
+        return false if count.zero?
+
+        kind = definition_kind(definition)
+        add(
+          :"forbidden_#{kind}",
+          "#{kind.capitalize} is forbidden by the selected profile",
+          **definition_context(definition, path),
+          details: { profile: profile.id, count: }
+        )
+        false
+      end
+
+      def missing(definition, path, cardinality)
+        kind = definition_kind(definition)
+        add(
+          :"missing_required_#{kind}",
+          "Required #{kind} is missing",
+          **definition_context(definition, path),
+          details: { profile: profile.id, cardinality: }
+        )
+      end
+
+      def invalid_cardinality(definition, count, path, cardinality)
+        add(
+          :invalid_cardinality,
+          'Value count exceeds the profile cardinality',
+          **definition_context(definition, path),
+          details: { profile: profile.id, cardinality:, count: }
+        )
+      end
+
+      def add(code, message, **context)
+        @issues << Issue.new(code:, message:, **context)
+      end
+
+      def definition_context(definition, path)
+        if definition.respond_to?(:group_id)
+          { term_id: definition.id, group_id: definition.group_id, path: path || definition.xpath }
+        else
+          { group_id: definition.id, path: path || definition.xpath }
+        end
+      end
+
+      def definition_kind(definition)
+        definition.respond_to?(:group_id) ? 'term' : 'group'
+      end
+
+      def required?(cardinality) = cardinality.start_with?('1')
+
+      def repeated?(cardinality) = cardinality.end_with?('n')
+    end
+    private_constant :Tracking
+
+    class Tracker
+      include Tracking
+
+      attr_reader :profile
+
+      def initialize(profile:)
+        @profile = profile
+        @issues = []
+      end
+
+      def check_guideline(guideline_urn, path: nil)
+        return if guideline_urn.nil? || guideline_urn == profile.guideline_urn
+
+        add(
+          :profile_mismatch,
+          'Document guideline does not match the selected profile',
+          term_id: 'BT-24',
+          path:,
+          details: { expected: profile.guideline_urn, actual: guideline_urn }
+        )
+      end
+
+      def check_document(document, path: nil)
+        check_guideline(document.guideline_urn, path:)
+      end
+
+      def observe_group?(group, count:, path: nil)
+        definition_observed?(group, count, path)
+      end
+
+      def observe_term?(term, values:, path: nil)
+        definition_observed?(term, values.size, path)
+      end
+
+      def invalid_term(term, error:, path: nil)
+        raise TypeError, 'error must be a FormattingError' unless error.is_a?(FormattingError)
+
+        add(
+          :invalid_value,
+          error.message,
+          term_id: term.id,
+          group_id: term.group_id,
+          path: path || error.details[:path] || term.xpath,
+          details: error.details
+        )
+      end
+
+      def unrepresentable_attribute(group, model:, attribute:, path: nil)
+        add(
+          :unrepresentable_attribute,
+          'Model attribute cannot be represented in this group',
+          group_id: group.id,
+          path: path || group.xpath,
+          details: { model:, attribute: }
+        )
+      end
+
+      def report
+        Report.new(profile:, issues: @issues)
+      end
+    end
+  end
+end