facturx 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10cd4d86db6d643606dbd85da9ced31d20e884249505e8a608ebb864f9a2f2ef
-  data.tar.gz: 3e0665c807043cdca83550452ab2b1e3ca7d40b759105eea8856916a316576fd
+  metadata.gz: 61ff49d55f56bb55d9b6624eb58fd59e16ed016672464f72507ea21b556c3050
+  data.tar.gz: 3f6be26b5cb8a65ea5d024cc68c709835154cd67fd48147d4a184182f7938c19
 SHA512:
-  metadata.gz: 0cf6cb2b75adb6a668a5746420ee82177aada0c87d9d40bd625387a59d1409b63ef53916df3480aa7adaf539b59c99fb635667134e3cefcbd66590f1a19aeecd
-  data.tar.gz: 3e7715e0181e11b9b0589ab85da8194e692647fcb4be0d42d177968584d0cc1f1e2114a782e8d533c7c5a2fbac0943bc2bd4964e59633773c9dd864e5a42cee4
+  metadata.gz: 071dce1b5bb8ca3925152e2c0b5bcebaff0b2d73399d7e681f9407eeb59bb0ba981dbcbc194cb9b8faace203cdddc7ba5b332c22e92b377b3082d2641dacce8b
+  data.tar.gz: 1ffab4f27f2f0ba54e6ffcf3e5d949aafecde9dd92c758acb1f3a1c9f4a1792794b2c91372d564ec49c917114c715f061d90843a14393fabac44bb0058af03c7

data/CHANGELOG.md

@@ -4,6 +4,27 @@ 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
@@ -37,7 +58,8 @@ All notable changes to this project will be documented in this file.
 - Compose PDF/A-3b Factur-X documents with Ghostscript.
 - Extract embedded Factur-X XML from PDF documents.
 
-[Unreleased]: https://github.com/AdVitam/facturx/compare/v1.0.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,133 +1,111 @@
-# facturx
+# Facturx
 
-`facturx` builds, 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'
-```
+### Main workflows
 
-Then run `bundle install`.
+| | 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` |
 
-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.
+### Focused tools
 
-## Usage
+| | 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` |
 
-All inputs and outputs are byte strings. The gem does not interpret strings as file paths.
+### Boundaries
 
-```ruby
-require 'facturx'
+| | Capability | Responsibility |
+|:---:|---|---|
+| ⏳ | Schematron business rules | Planned |
+| ➖ | Invoice calculations | Application |
+| ➖ | Visual PDF generation | Application |
+| ➖ | PDP transport and e-invoicing | Application |
 
-xml = File.binread('invoice.xml')
-pdf = File.binread('invoice.pdf')
+✅ Supported · ⏳ Planned · ➖ Intentionally handled outside the gem
 
-Facturx.verify_xml(xml: xml)
+## Supported profiles
 
-reading = Facturx.read(xml)
-reading.document.invoice_number
-reading.document.totals.grand_total
-reading.diagnostics
+Facturx supports Factur-X 1.09.2 / ZUGFeRD 2.5.2.
 
-facturx_pdf = Facturx.attach(pdf: pdf, xml: xml)
-File.binwrite('invoice-facturx.pdf', facturx_pdf)
+| Profile | Read | Build | XSD validation |
+|---|:---:|:---:|:---:|
+| MINIMUM | ✅ | ✅ | ✅ |
+| BASIC WL | ✅ | ✅ | ✅ |
+| BASIC | ✅ | ✅ | ✅ |
+| EN 16931 | ✅ | ✅ | ✅ |
+| EXTENDED | ✅* | ✅* | ✅ |
 
-embedded_xml = Facturx.extract_xml(pdf: facturx_pdf)
-pdf_reading = Facturx.read(facturx_pdf)
-```
+\* EXTENDED-only fields that are not represented by the typed model remain available in the original XML and are reported through diagnostics.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- Ghostscript 9.54 or newer, `zugferd.ps`, and an RGB ICC profile for PDF composition only
+
+XML building, reading, extraction, and validation require no external executable.
+
+## Quick start
 
-Build a typed document with the nested DSL, validate it without generating XML, or generate XML and attach it to an existing PDF:
+Turn an existing invoice PDF and typed business data into a PDF/A-3b Factur-X invoice with XSD-validated XML:
 
 ```ruby
+require 'facturx'
+
 document = Facturx::Document.build(
   invoice_number: 'INV-2026-0042',
   type_code: '380',
-  issue_date: Date.new(2026, 9, 12),
+  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
 
-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.
+source_pdf = File.binread('invoice.pdf')
+facturx_pdf = Facturx.generate(pdf: source_pdf, document:, profile: :minimum)
 
-`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
-
-The composer searches common installation paths. Override discovery when necessary:
-
-```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
-
-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.
+`generate` validates the document and generated XML, embeds `factur-x.xml`, and verifies the resulting PDF metadata and attachment.
 
-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.
+## Documentation
 
-## Development
+See [DOCUMENTATION.md](DOCUMENTATION.md) to:
 
-```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/error.rb

@@ -10,12 +10,15 @@ module Facturx
     end
   end
 
-  class InvalidXmlError < Error; end
+  class ValidationError < Error; end
+  class InvalidDocumentError < ValidationError; end
+  class InvalidXmlError < ValidationError; end
   class UnknownProfileError < InvalidXmlError; end
   class XsdValidationError < InvalidXmlError; end
+  class SchemaLoadError < Error; end
+  class InvalidSourceError < Error; end
   class UnsupportedProfileError < Error; end
   class FormattingError < Error; end
-  class ConformanceError < Error; end
   class InvalidPdfError < Error; end
   class ProtectedPdfError < InvalidPdfError; end
   class ComposerUnavailableError < Error; end

data/lib/facturx/generate.rb

@@ -1,21 +1,21 @@
 # frozen_string_literal: true
 
-require_relative 'attach'
+require_relative 'pdf/composer'
 require_relative 'profile_resolver'
 require_relative 'writer'
 
 module Facturx
   class Generate
-    def initialize(writer: Writer.new, attacher: Attach.new, profile_resolver: ProfileResolver.new)
+    def initialize(writer: Writer.new, pdf_composer: Pdf::Composer.new, profile_resolver: ProfileResolver.new)
       @writer = writer
-      @attacher = attacher
+      @pdf_composer = pdf_composer
       @profile_resolver = profile_resolver
     end
 
     def call(pdf:, document:, profile:)
       canonical_profile = @profile_resolver.call(profile)
       xml = @writer.call(document:, profile: canonical_profile)
-      @attacher.call(pdf:, xml:)
+      @pdf_composer.call(pdf:, xml:, profile: canonical_profile)
     end
   end
 end

data/lib/facturx/pdf/composer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'inspector'
+require_relative 'extractor'
+require_relative 'verifier'
+require_relative '../composers/ghostscript'
+
+module Facturx
+  module Pdf
+    class Composer
+      def initialize(
+        inspector: Inspector.new,
+        backend: Composers::Ghostscript.new,
+        extractor: Extractor.new,
+        verifier: Verifier.new
+      )
+        @inspector = inspector
+        @backend = backend
+        @extractor = extractor
+        @verifier = verifier
+      end
+
+      def call(pdf:, xml:, profile:)
+        inspection = @inspector.call(pdf)
+        output = @backend.call(pdf:, xml:, profile:)
+        result = @extractor.call(output)
+        @verifier.call(result:, expected_xml: xml, expected_page_count: inspection.page_count, profile:)
+        output
+      end
+    end
+  end
+end

data/lib/facturx/profile.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Facturx
-  Profile = Data.define(:id, :guideline_urn, :xsd_path, :conformance_level)
+  Profile = Data.define(:id, :guideline_urn, :conformance_level)
 end