facturx 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10cd4d86db6d643606dbd85da9ced31d20e884249505e8a608ebb864f9a2f2ef
-  data.tar.gz: 3e0665c807043cdca83550452ab2b1e3ca7d40b759105eea8856916a316576fd
+  metadata.gz: 8beb5aea7a14256c4d062dfbf732462016ec2e0eaacafedf016235f085353eee
+  data.tar.gz: 24ea8be809ed5b980cb01b2dee2a775c76c21ae717dda9c056182880bfc44e3d
 SHA512:
-  metadata.gz: 0cf6cb2b75adb6a668a5746420ee82177aada0c87d9d40bd625387a59d1409b63ef53916df3480aa7adaf539b59c99fb635667134e3cefcbd66590f1a19aeecd
-  data.tar.gz: 3e7715e0181e11b9b0589ab85da8194e692647fcb4be0d42d177968584d0cc1f1e2114a782e8d533c7c5a2fbac0943bc2bd4964e59633773c9dd864e5a42cee4
+  metadata.gz: 93279c7e5faaebe8aa8d2b4c645f739e6a70517fa530340186621af496b95e3ec29b5f84a99fcb6edfadb0601013e0b945d3aaf2440eb02aa30c395eb06f5f6e
+  data.tar.gz: 04af7d886516bebfa086252a99892721b9a9a775271e35abc94641ac40fbfbb70865be020cf93b41123c317ae794d823ec7ce0104119f0a7cdb8829d6ac3ba64

data/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-09-14
+
+### Add
+
+- Add optional official Schematron validation through the lightweight `facturx-schematron` companion gem.
+- Add Schematron issues and strict errors to the existing validation model for all writing and attachment workflows.
+- Add shared bounded subprocess execution for Ghostscript and SaxonC without loading optional rules in the core gem.
+
+### Fix
+
+- Preserve non-UTF-8 invoice text when passing parsed XML to SaxonC.
+- Report oversized Schematron output as a resource limit instead of malformed validation output.
+- Keep subprocess timeout diagnostics valid UTF-8 while preserving raw successful output bytes.
+
+## [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 +72,9 @@ 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.2.0...HEAD
+[1.2.0]: https://github.com/AdVitam/facturx/compare/v1.1.0...v1.2.0
+[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,302 @@
+# 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
+```
+
+Core validation issues use the `:error` severity. The optional Schematron validator also preserves official `:warning` findings, which do not invalidate a report.
+
+Generated documents always 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. When enabled, Schematron runs after these core checks as a third validation layer.
+
+### Optional Schematron validation
+
+Install the companion gem to add the official Factur-X 1.09.2 business rules without increasing the core gem's package or runtime footprint:
+
+```ruby
+gem 'facturx'
+gem 'facturx-schematron', require: 'facturx/schematron'
+```
+
+Alternatively, require it explicitly after Bundler setup:
+
+```ruby
+require 'facturx'
+require 'facturx/schematron'
+```
+
+Loading the companion enables Schematron after XSD validation for `validate_xml`, `validate_document`, `attach`, `build_xml`, and `generate`. Public method signatures and report types remain unchanged. `read` stays tolerant and does not validate implicitly.
+
+The companion requires SaxonC-HE's `Transform` executable, version 12.10 or newer. Put it in `PATH`, or provide its absolute path:
+
+```bash
+export FACTURX_SAXONC_TRANSFORM=/opt/saxonc/bin/Transform
+```
+
+Loading fails immediately with `Facturx::Schematron::UnavailableError` when the executable is missing, cannot start, or is unsupported. Runtime engine failures raise `Facturx::Schematron::ExecutionError`; they never fall back silently to XSD-only validation.
+
+Schematron findings use the `:schematron` layer and expose the official rule ID, test, and flag in `issue.details`. Official warnings keep reports valid; assertions without a warning flag are errors. Strict XML workflows raise `Facturx::SchematronValidationError` for blocking findings.
+
+The companion ships only the five official compiled XSLT stylesheets and adjacent code databases. Each successful validation starts one isolated SaxonC subprocess, so applications processing large batches should account for native process startup and memory in their worker sizing.
+
+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::SchematronValidationError` | XML violates an enabled Schematron business rule |
+| `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 alone is not complete regulatory validation. The optional companion runs the official Schematron rules, but Facturx does not calculate invoice values or replace application-level accounting controls.
+
+## 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. The optional Schematron integration reuses the same bounded process lifecycle for SaxonC.
+
+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 rake
+bundle exec rake build_all
+```
+
+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,115 @@
-# 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` |
+| 🔌 | Add official Schematron business-rule validation | `facturx-schematron` |
+| ✅ | 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 |
+|:---:|---|---|
+| ➖ | Invoice calculations | Application |
+| ➖ | Visual PDF generation | Application |
+| ➖ | PDP transport and e-invoicing | Application |
 
-xml = File.binread('invoice.xml')
-pdf = File.binread('invoice.pdf')
+✅ Included · 🔌 Optional companion · ➖ 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 | Schematron** |
+|---|:---:|:---:|:---:|:---:|
+| 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.
+
+\** Available through the optional `facturx-schematron` gem.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- Ghostscript 9.54 or newer, `zugferd.ps`, and an RGB ICC profile for PDF composition only
+- SaxonC-HE 12.10 or newer only when `facturx-schematron` is enabled
+
+Core XML building, reading, extraction, and XSD validation require no external executable.
 
-Build a typed document with the nested DSL, validate it without generating XML, or generate XML and attach it to an existing PDF:
+## Quick start
+
+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.
+source_pdf = File.binread('invoice.pdf')
+facturx_pdf = Facturx.generate(pdf: source_pdf, document:, profile: :minimum)
 
-`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
-
-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
+`generate` validates the document and generated XML, embeds `factur-x.xml`, and verifies the resulting PDF metadata and attachment.
 
-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.
+## Documentation
 
-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.
+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;
+- enable official Schematron business-rule validation;
+- 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