facturx 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6318d858bdc82dd508e53e66c6f41ea56e455ce55df676b9e5268fa881f7a98
-  data.tar.gz: 8b182edb44be499ec57bb1b0f98ecf892290584c0f959b73e7c787be460188d1
+  metadata.gz: 61ff49d55f56bb55d9b6624eb58fd59e16ed016672464f72507ea21b556c3050
+  data.tar.gz: 3f6be26b5cb8a65ea5d024cc68c709835154cd67fd48147d4a184182f7938c19
 SHA512:
-  metadata.gz: b529dd611b8f5c71c6aa9b9d9458ffeea4352fee2e62030e74f543a464d008c4b97bd186313b13d7b1966abf4f1614b13b9797729d7ece243aa71045e032e03b
-  data.tar.gz: 4a25ca0ef9d9f4df72150925753a250989316a2a31e171b0b14de85e342950408ebc43d5d4d3150a91863fe07b6a805271bbda7fa3a2f9c2502c68d18111918d
+  metadata.gz: 071dce1b5bb8ca3925152e2c0b5bcebaff0b2d73399d7e681f9407eeb59bb0ba981dbcbc194cb9b8faace203cdddc7ba5b332c22e92b377b3082d2641dacce8b
+  data.tar.gz: 1ffab4f27f2f0ba54e6ffcf3e5d949aafecde9dd92c758acb1f3a1c9f4a1792794b2c91372d564ec49c917114c715f061d90843a14393fabac44bb0058af03c7

data/CHANGELOG.md

@@ -4,9 +4,47 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-14
+
+### Add
+
+- Add packaged reference documentation for the public API and operational constraints.
+- Add structured XML and document validation reports with a shared issue model.
+- Add precise errors for invalid input sources, invalid documents, and unavailable schemas.
+
+### Fix
+
+- Validate generated XML only once before composing and verifying the PDF.
+- Limit the supported public surface to facades, domain values, results, profiles, and emitted errors.
+- Keep profile metadata independent from the bundled schema layout.
+- Expose strict XML failures from `attach` through the shared validation report and issue model.
+
+### Del
+
+- Remove `verify_xml`, `Conformance` reports, `ConformanceError`, and direct access to implementation services.
+- Remove `Profile#xsd_path` and the public schema layout constants from `Profiles`.
+- Make the internal `Profiles` lookup constants private; use `Profiles.all`, `.fetch`, or `.for_guideline_urn`.
+
+## [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
 
-### Added
+### 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.
@@ -14,12 +52,14 @@ All notable changes to this project will be documented in this file.
 
 ## [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.2.0...HEAD
+[Unreleased]: https://github.com/AdVitam/facturx/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/AdVitam/facturx/compare/v1.0.0...v1.1.0
+[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/DOCUMENTATION.md

@@ -0,0 +1,271 @@
+# Facturx documentation
+
+## Contents
+
+- [Public API](#public-api)
+- [Build an invoice](#build-an-invoice)
+- [Use an existing XML invoice](#use-an-existing-xml-invoice)
+- [Read a received invoice](#read-a-received-invoice)
+- [Profiles](#profiles)
+- [Validation](#validation)
+- [PDF composition](#pdf-composition)
+- [Round-trip guarantees](#round-trip-guarantees)
+- [Security and resource usage](#security-and-resource-usage)
+- [Development](#development)
+
+## Public API
+
+All PDF and XML inputs and outputs are byte strings. Facturx never interprets a string as a file path.
+
+The three primary workflows are:
+
+| Operation | API | Result |
+|---|---|---|
+| Build and embed XML | `Facturx.generate(pdf:, document:, profile:)` | PDF/A-3b bytes |
+| Read XML or PDF | `Facturx.read(source)` | `Facturx::Reading` |
+| Embed existing XML | `Facturx.attach(pdf:, xml:)` | PDF/A-3b bytes |
+
+Focused operations are available when the complete workflow is not needed:
+
+| Operation | API | Result |
+|---|---|---|
+| Validate XML | `Facturx.validate_xml(xml:)` | `Facturx::Validation::Report` |
+| Validate typed data | `Facturx.validate_document(document:, profile:)` | `Facturx::Validation::Report` |
+| Build XML | `Facturx.build_xml(document:, profile:)` | XML bytes |
+| Extract embedded XML | `Facturx.extract_xml(pdf:)` | Exact embedded XML bytes |
+
+## Build an invoice
+
+`Facturx::Document.build` provides a nested DSL for the immutable Factur-X model. Singular associations accept either keyword attributes or a block; repeating associations use singular helpers such as `line`, `note`, and `tax_breakdown`.
+
+```ruby
+document = Facturx::Document.build(
+  invoice_number: 'INV-2026-0042',
+  type_code: '380',
+  issue_date: Date.new(2026, 9, 13),
+  currency: 'EUR'
+) do |invoice|
+  invoice.seller do |seller|
+    seller.name = 'Seller SAS'
+    seller.address(
+      line_one: '10 Example Street',
+      postcode: '75001',
+      city: 'Paris',
+      country_code: 'FR'
+    )
+    seller.vat_identifier(value: 'FR00123456789')
+  end
+
+  invoice.buyer do |buyer|
+    buyer.name = 'Buyer SAS'
+    buyer.address(country_code: 'FR')
+  end
+
+  invoice.line do |line|
+    line.id = '1'
+    line.product(name: 'Consulting services')
+    line.quantity(value: BigDecimal('1'), unit_code: 'C62')
+    line.net_price(amount: BigDecimal('100.00'))
+    line.tax(category_code: 'S', rate: BigDecimal('20.00'))
+    line.net_amount = BigDecimal('100.00')
+  end
+
+  invoice.tax_breakdown(
+    category_code: 'S',
+    rate: BigDecimal('20.00'),
+    basis_amount: BigDecimal('100.00'),
+    tax_amount: BigDecimal('20.00')
+  )
+
+  invoice.totals(
+    line_total: BigDecimal('100.00'),
+    tax_basis_total: BigDecimal('100.00'),
+    tax_total: BigDecimal('20.00'),
+    grand_total: BigDecimal('120.00'),
+    due_payable: BigDecimal('120.00')
+  )
+end
+```
+
+Choose one of `:minimum`, `:basic_wl`, `:basic`, `:en16931`, or `:extended` when validating or generating a document:
+
+```ruby
+source_pdf = File.binread('invoice.pdf')
+facturx_pdf = Facturx.generate(pdf: source_pdf, document:, profile: :en16931)
+```
+
+`generate` performs document and XSD validation before composing the PDF. Use `validate_document` to collect every semantic issue without raising, or `build_xml` when only the XML is needed:
+
+```ruby
+report = Facturx.validate_document(document:, profile: :en16931)
+
+report.issues.each { |issue| warn issue.message } if report.invalid?
+```
+
+Alternatively, call `build_xml` directly and rescue `Facturx::InvalidDocumentError` when the report is only needed on failure.
+
+`build_xml` and `generate` raise `Facturx::InvalidDocumentError` with the same report in `error.details[:report]` when the document is invalid.
+
+The writer inserts the selected profile's canonical BT-24 guideline URN when it is absent. It reports a profile mismatch when the document contains a conflicting value. Values are serialized from their declared semantic type; monetary values with more than two decimal places are rejected rather than rounded implicitly.
+
+## Use an existing XML invoice
+
+Validate XML against the XSD selected by its BT-24 guideline URN:
+
+```ruby
+xml = File.binread('invoice.xml')
+report = Facturx.validate_xml(xml:)
+report.valid?
+```
+
+`validate_xml` reports malformed XML, a missing or unknown BT-24 profile, and every XSD violation without raising. A non-`String` input raises `Facturx::InvalidSourceError`; internal failures such as an unavailable bundled schema also raise a typed `Facturx::Error`.
+
+Document validation reports all semantic issues in one pass. XSD validation runs only after that semantic layer succeeds, avoiding structural noise from XML already known to be incomplete.
+
+Attach valid XML to an existing visual invoice PDF:
+
+```ruby
+pdf = File.binread('invoice.pdf')
+facturx_pdf = Facturx.attach(pdf:, xml:)
+
+File.binwrite('invoice-facturx.pdf', facturx_pdf)
+```
+
+`attach` validates the XML, converts the input to PDF/A-3b, embeds the original bytes as `factur-x.xml`, and verifies the attachment and Factur-X metadata. It rejects signed or encrypted PDFs because rewriting them would invalidate their protection.
+
+Extracting XML is deliberately independent from validation:
+
+```ruby
+embedded_xml = Facturx.extract_xml(pdf: facturx_pdf)
+Facturx.validate_xml(xml: embedded_xml)
+```
+
+This separation keeps malformed third-party invoices inspectable.
+
+## Read a received invoice
+
+`read` accepts either XML or PDF bytes and returns an immutable `Facturx::Reading`:
+
+```ruby
+reading = Facturx.read(File.binread('received-invoice.pdf'))
+
+reading.document.invoice_number
+reading.document.totals.grand_total
+reading.profile.id
+reading.diagnostics
+reading.source
+reading.source_type
+```
+
+Dates are `Date`, decimals are `BigDecimal`, identifiers retain their schemes, and repeating groups are frozen arrays in XML order. `source` contains the exact XML bytes and `source_type` is either `:xml` or `:pdf`.
+
+Reading is tolerant and does not run implicit XSD validation. Missing, duplicate, empty, invalid, or unmapped values produce immutable diagnostics while usable fields remain accessible. Call `validate_xml` when structural validation is required.
+
+Unknown or missing BT-24 values fall back to the EN 16931 intersection represented by the EXTENDED profile and add a diagnostic. Reject them instead with:
+
+```ruby
+Facturx.read(xml, on_unknown_profile: :raise)
+```
+
+## Profiles
+
+The five canonical profiles are available through `Facturx::Profiles`:
+
+```ruby
+profile = Facturx::Profiles.fetch(:en16931)
+
+profile.id
+profile.guideline_urn
+profile.conformance_level
+```
+
+Public writer methods accept either a profile symbol or its canonical `Facturx::Profile`. A separate profile object with matching attributes is rejected to keep profile resolution tied to the bundled XSD and metadata definitions.
+
+The semantic registry covers all 184 EN 16931 business terms and the MINIMUM, BASIC WL, and BASIC subsets. EXTENDED-only fields remain available in `Reading#source` and produce diagnostics until represented in the typed model.
+
+## Validation
+
+`validate_xml` and `validate_document` return the same immutable report. Each issue identifies its validation layer, severity, message, and available XML or business-term location. A report can therefore be inspected without rescuing expected validation failures:
+
+```ruby
+report.issues.each do |issue|
+  warn "#{issue.layer}: #{issue.term_id || issue.path} #{issue.message}"
+end
+```
+
+All issues currently emitted use the `:error` severity. The `:warning` severity is reserved for planned Schematron diagnostics.
+
+Generated documents pass through two layers:
+
+1. semantic conformance checks against the selected profile's business-term cardinalities and supported model mappings;
+2. structural validation against the bundled official profile XSD.
+
+Incoming XML passed to `validate_xml` is parsed, resolved to a profile from BT-24, and checked against that profile's XSD.
+
+Domain failures use a `Facturx::Error` subclass with structured context in `details`. Common errors include:
+
+| Error | Meaning |
+|---|---|
+| `Facturx::ValidationError` | Base class for strict validation failures |
+| `Facturx::InvalidXmlError` | XML cannot be parsed |
+| `Facturx::UnknownProfileError` | BT-24 is absent or unsupported during strict XML validation |
+| `Facturx::XsdValidationError` | XML does not satisfy the selected profile XSD |
+| `Facturx::UnsupportedProfileError` | A writer profile is unsupported |
+| `Facturx::InvalidDocumentError` | A typed document violates the selected profile |
+| `Facturx::InvalidSourceError` | An XML or reader source is not a byte `String` |
+| `Facturx::SchemaLoadError` | A bundled validation schema cannot be loaded |
+| `Facturx::ProtectedPdfError` | The source PDF is signed or encrypted |
+| `Facturx::ComposerUnavailableError` | Required Ghostscript resources are unavailable |
+| `Facturx::CompositionError` | Ghostscript composition failed |
+| `Facturx::ExtractionError` | The embedded Factur-X XML cannot be selected or decoded |
+| `Facturx::VerificationError` | The composed PDF does not match the requested invoice |
+
+XSD validation is not complete regulatory validation. Facturx does not yet run the official Schematron business rules, calculate totals, or evaluate accounting consistency.
+
+## PDF composition
+
+PDF composition through `attach` or `generate` requires:
+
+- Ghostscript 9.54 or newer;
+- Ghostscript's `zugferd.ps` script;
+- an RGB ICC profile.
+
+These resources are not distributed with the gem. Facturx searches common installation paths and accepts explicit overrides when automatic discovery is not suitable:
+
+```bash
+export GHOSTSCRIPT_BIN=/opt/ghostscript/bin/gs
+export FACTURX_ZUGFERD_PS=/opt/ghostscript/share/ghostscript/lib/zugferd.ps
+export FACTURX_ICC_PROFILE=/opt/ghostscript/share/ghostscript/iccprofiles/default_rgb.icc
+```
+
+The composer invokes Ghostscript as an external process with a timeout, bounded output capture, and file access restricted to its staged inputs and outputs.
+
+Facturx does not create the visual invoice. The supplied PDF remains the visual source that is converted to PDF/A-3b and enriched with Factur-X XML and metadata.
+
+## Round-trip guarantees
+
+The reader preserves the exact incoming XML in `Reading#source`, but reading and rebuilding is not a fidelity round-trip. The writer cannot reproduce values outside the typed semantic model.
+
+Retain and reuse `Reading#source` when reissuing an incoming invoice without intentional semantic changes.
+
+## Security and resource usage
+
+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.
+
+Facturx does not communicate with a PDP or implement e-invoicing transport. Network submission, authentication, retries, storage, invoice calculations, and business approval workflows remain application responsibilities.
+
+## Development
+
+```bash
+mise install
+bundle install
+bundle exec rubocop
+bundle exec rspec
+bundle exec rake build
+```
+
+Maintainers can compare the semantic registry, D22B mappings, diagnostics, official XML examples, and paired PDF attachments with an extracted upstream package:
+
+```bash
+FACTURX_REFERENCE_ROOT=/path/to/ZUGFeRD_2.5.2_EN bundle exec rake reference:verify
+```

data/README.md

@@ -1,101 +1,111 @@
-# facturx
+# Facturx
 
-`facturx` reads and validates Factur-X XML, creates PDF/A-3b Factur-X invoices from existing PDFs, and extracts their embedded XML.
+[![Gem Version](https://badge.fury.io/rb/facturx.svg)](https://rubygems.org/gems/facturx)
+[![Test](https://github.com/AdVitam/facturx/actions/workflows/test.yml/badge.svg)](https://github.com/AdVitam/facturx/actions/workflows/test.yml)
+[![Ruby](https://img.shields.io/badge/Ruby-3.2%2B-CC342D.svg)](https://www.ruby-lang.org)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
 
-The first release supports Factur-X 1.09.2 / ZUGFeRD 2.5.2 with the MINIMUM, BASIC WL, BASIC, EN 16931, and EXTENDED profiles.
+Build, read, validate, and compose Factur-X / ZUGFeRD invoices in Ruby.
 
-## Installation
+Use typed Ruby objects to generate XSD-valid XML, embed it into an existing PDF, or inspect invoices received from third parties.
 
-Add the gem to your bundle:
+## Features
 
-```ruby
-gem 'facturx'
-```
-
-Then run `bundle install`.
+### Main workflows
 
-Composition requires Ghostscript 9.54 or newer with `zugferd.ps` and an RGB ICC profile installed on the system. Package contents vary by operating system and distribution: after installing Ghostscript, verify that both resources are present and configure their paths as described below when automatic discovery cannot find them.
+| | What you need | API |
+|:---:|---|---|
+| ✅ | Generate a Factur-X invoice from typed data | `Facturx::Document.build` + `Facturx.generate` |
+| ✅ | Read an XML or PDF invoice | `Facturx.read` |
+| ✅ | Embed existing Factur-X XML into a PDF | `Facturx.attach` |
 
-## Usage
+### Focused tools
 
-All inputs and outputs are byte strings. The gem does not interpret strings as file paths.
+| | Capability | API |
+|:---:|---|---|
+| ✅ | Generate Factur-X XML | `Facturx.build_xml` |
+| ✅ | Validate typed documents | `Facturx.validate_document` |
+| ✅ | Validate XML against official XSDs | `Facturx.validate_xml` |
+| ✅ | Extract the original embedded XML | `Facturx.extract_xml` |
 
-```ruby
-require 'facturx'
+### Boundaries
 
-xml = File.binread('invoice.xml')
-pdf = File.binread('invoice.pdf')
+| | Capability | Responsibility |
+|:---:|---|---|
+| ⏳ | Schematron business rules | Planned |
+| ➖ | Invoice calculations | Application |
+| ➖ | Visual PDF generation | Application |
+| ➖ | PDP transport and e-invoicing | Application |
 
-Facturx.verify_xml(xml: xml) # => true
+✅ Supported · ⏳ Planned · ➖ Intentionally handled outside the gem
 
-reading = Facturx.read(xml)
-reading.document.invoice_number # => "F-2023-004"
-reading.document.totals.grand_total # => BigDecimal("120.00")
-reading.diagnostics # => [] for a complete EN16931 document
+## Supported profiles
 
-facturx_pdf = Facturx.attach(pdf: pdf, xml: xml)
-File.binwrite('invoice-facturx.pdf', facturx_pdf)
+Facturx supports Factur-X 1.09.2 / ZUGFeRD 2.5.2.
 
-embedded_xml = Facturx.extract_xml(pdf: facturx_pdf)
-pdf_reading = Facturx.read(facturx_pdf)
-```
+| Profile | Read | Build | XSD validation |
+|---|:---:|:---:|:---:|
+| MINIMUM | ✅ | ✅ | ✅ |
+| BASIC WL | ✅ | ✅ | ✅ |
+| BASIC | ✅ | ✅ | ✅ |
+| EN 16931 | ✅ | ✅ | ✅ |
+| EXTENDED | ✅* | ✅* | ✅ |
 
-`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.
+\* EXTENDED-only fields that are not represented by the typed model remain available in the original XML and are reported through diagnostics.
 
-`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.
+## Requirements
 
-`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.
+- Ruby 3.2 or newer
+- Ghostscript 9.54 or newer, `zugferd.ps`, and an RGB ICC profile for PDF composition only
 
-`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`.
+XML building, reading, extraction, and validation require no external executable.
 
-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.
+## Quick start
 
-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:
+Turn an existing invoice PDF and typed business data into a PDF/A-3b Factur-X invoice with XSD-validated XML:
 
 ```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`; a future writer built from `Reading#document` 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
+require 'facturx'
 
-The composer searches common installation paths. Override discovery when necessary:
+document = Facturx::Document.build(
+  invoice_number: 'INV-2026-0042',
+  type_code: '380',
+  issue_date: Date.new(2026, 9, 13),
+  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'),
+    tax_total: BigDecimal('20.00'),
+    grand_total: BigDecimal('120.00'),
+    due_payable: BigDecimal('120.00')
+  )
+end
+
+source_pdf = File.binread('invoice.pdf')
+facturx_pdf = Facturx.generate(pdf: source_pdf, document:, profile: :minimum)
 
-```bash
-export GHOSTSCRIPT_BIN=/opt/ghostscript/bin/gs
-export FACTURX_ZUGFERD_PS=/opt/ghostscript/share/ghostscript/lib/zugferd.ps
-export FACTURX_ICC_PROFILE=/opt/ghostscript/share/ghostscript/iccprofiles/default_rgb.icc
+File.binwrite('invoice-facturx.pdf', facturx_pdf)
 ```
 
-The gem invokes Ghostscript as an external process. It does not distribute Ghostscript, `zugferd.ps`, or ICC profiles.
-
-## Validation scope
+`generate` validates the document and generated XML, embeds `factur-x.xml`, and verifies the resulting PDF metadata and attachment.
 
-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.
+## Documentation
 
-The gem does not generate invoice XML or the visual invoice PDF, communicate with a PDP, or implement e-reporting.
+See [DOCUMENTATION.md](DOCUMENTATION.md) to:
 
-## Development
-
-```bash
-mise install
-bundle install
-bundle exec rubocop
-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
-```
+- build richer typed invoices;
+- validate or attach existing XML;
+- read invoices and handle diagnostics;
+- understand profiles, validation boundaries, and typed errors;
+- configure Ghostscript for PDF/A-3b composition.
 
 ## License
 
-The gem code is available under the MIT License. Bundled standard artefacts retain their respective upstream notices; see `NOTICE.md`.
+The gem code is available under the [MIT License](LICENSE.txt). Bundled standard artefacts retain their respective upstream notices; see [NOTICE.md](NOTICE.md).

data/lib/facturx/attach.rb

@@ -1,34 +1,18 @@
 # frozen_string_literal: true
 
 require_relative 'xml/verifier'
-require_relative 'pdf/inspector'
-require_relative 'pdf/extractor'
-require_relative 'pdf/verifier'
-require_relative 'composers/ghostscript'
+require_relative 'pdf/composer'
 
 module Facturx
   class Attach
-    def initialize(
-      xml_verifier: Xml::Verifier.new,
-      pdf_inspector: Pdf::Inspector.new,
-      composer: Composers::Ghostscript.new,
-      extractor: Pdf::Extractor.new,
-      pdf_verifier: Pdf::Verifier.new
-    )
+    def initialize(xml_verifier: Xml::Verifier.new, pdf_composer: Pdf::Composer.new)
       @xml_verifier = xml_verifier
-      @pdf_inspector = pdf_inspector
-      @composer = composer
-      @extractor = extractor
-      @pdf_verifier = pdf_verifier
+      @pdf_composer = pdf_composer
     end
 
     def call(pdf:, xml:)
       profile = @xml_verifier.call(xml:)
-      inspection = @pdf_inspector.call(pdf)
-      output = @composer.call(pdf:, xml:, profile:)
-      result = @extractor.call(output)
-      @pdf_verifier.call(result:, expected_xml: xml, expected_page_count: inspection.page_count, profile:)
-      output
+      @pdf_composer.call(pdf:, xml:, profile:)
     end
   end
 end

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