WIP: Add SA regime and ZATCA addon

[migueltorresvalls]

• Replace this bullet list with your changes

Pre-Review Checklist

• Opened this PR as a draft
• Read the CONTRIBUTING.md guide.
• Performed a self-review of my code.
• Added thorough tests with at least 90% code coverage.
• Modified or created example GOBL documents to show my changes in use, if appropriate.
• Added links to the source of the changes in tax regimes or addons, either structured or in the comments.
• Run go generate . to ensure that the Schemas and Regime data are up to date.
• Reviewed and fixed all linter warnings.
• Been obsessive with pointer nil checks to avoid panics.
• Updated the CHANGELOG.md with an overview of my changes.
• Marked this PR as ready for review.

And if you are part of the org:

• Requested a review from Copilot and fixed or dismissed (with a reason) all the feedback raised.
• Requested a review from @samlown.

[codecov]

Codecov Report

❌ Patch coverage is 98.75000% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.23%. Comparing base (72beee4) to head (0718b58).

Files with missing lines	Patch %	Lines
addons/sa/zatca/bill_invoices.go	97.81%	2 Missing and 2 partials ⚠️
addons/sa/zatca/tax_combo.go	95.55%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #777      +/-   ##
==========================================
+ Coverage   93.09%   93.23%   +0.13%     
==========================================
  Files         368      379      +11     
  Lines       19624    20104     +480     
==========================================
+ Hits        18269    18743     +474     
- Misses        919      922       +3     
- Partials      436      439       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds first-class support for Saudi Arabia (SA) to GOBL by introducing an SA tax regime (VAT) and a ZATCA e-invoicing addon, along with generated rule/schema artifacts and end-to-end examples that exercise the new regime/addon behavior.

Changes:

• Introduce regimes/sa with VAT category/rate definitions and SA-specific identity validation + normalization.
• Add addons/sa/zatca (sa-zatca-v1) defining extensions, scenarios, normalizers, and validations for ZATCA BR-KSA requirements (with thorough tests).
• Register the new regime/addon and update generated schemas/rules/regime/addon JSON plus SA example documents and rendered outputs.

Reviewed changes

Copilot reviewed 38 out of 42 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
regimes/sa/sa.go	Defines and registers the SA regime and its normalizer/rules.
regimes/sa/tax_categories.go	Adds SA VAT category and rate definitions (5%→15%).
regimes/sa/tax_identity.go	Adds SA VAT ID validation rule + normalization hook.
regimes/sa/tax_identity_test.go	Tests SA VAT ID validation and normalization.
regimes/sa/org_identities.go	Adds allowed SA organization identity types + validation rules.
regimes/sa/org_identities_test.go	Tests org identity behavior under SA regime.
regimes/sa/bill_invoices.go	Adds SA invoice supplier rules around tax ID and optional identity.
regimes/sa/bill_invoices_test.go	Tests SA invoice supplier rule behavior.
regimes/regimes.go	Registers SA regime in the global regimes import list.
addons/sa/zatca/zatca.go	Registers the sa-zatca-v1 addon and its rule sets/normalizers.
addons/sa/zatca/extensions.go	Defines ZATCA extension keys and the invoice-type code catalogue.
addons/sa/zatca/scenarios.go	Adds addon scenario defaults for invoices (doc type 388).
addons/sa/zatca/bill_invoices.go	Implements core ZATCA invoice validation rules (BR-KSA-*).
addons/sa/zatca/bill_invoices_test.go	Comprehensive tests covering ZATCA invoice rules/fixtures.
addons/sa/zatca/org_party.go	Adds SA address validation rules under ZATCA addon.
addons/sa/zatca/org_party_test.go	Tests SA address requirements and gating by country.
addons/sa/zatca/tax_combo.go	Adds VATEX/category constraints for ZATCA tax combos + normalization.
addons/sa/zatca/tax_combo_test.go	Tests VATEX/category constraints and normalization behavior.
addons/sa/zatca/cal_period.go	Adds BR-KSA-35 period start/end constraint.
addons/sa/zatca/cal_period_test.go	Tests BR-KSA-35 supply period constraint.
addons/sa/zatca/bill.go	Adds invoice normalizer tweaks (rounding/issue_time/outside-scope percent).
addons/addons.go	Registers ZATCA addon in the global addons import list.
examples/sa/standard-invoice.yaml	Adds SA standard invoice example using sa-zatca-v1.
examples/sa/standard-usd-invoice.yaml	Adds SA standard invoice example with FX rate USD→SAR.
examples/sa/simplified-invoice.yaml	Adds SA simplified invoice example using sa-zatca-v1.
examples/sa/credit-note-summary.yaml	Adds SA credit note summary example using sa-zatca-v1.
examples/sa/out/standard-invoice.json	Generated output for SA standard invoice example.
examples/sa/out/standard-usd-invoice.json	Generated output for SA USD invoice example.
examples/sa/out/simplified-invoice.json	Generated output for SA simplified invoice example.
examples/sa/out/credit-note-summary.json	Generated output for SA credit note summary example.
data/schemas/tax/regime-code.json	Adds SA to the regime-code schema enum.
data/schemas/tax/addon-list.json	Adds sa-zatca-v1 to the addon-list schema enum.
data/regimes/sa.json	Generated SA regime definition JSON.
data/addons/sa-zatca-v1.json	Generated ZATCA addon definition JSON.
data/catalogues/cef.json	Adds SA VATEX codes to the CEF VATEX catalogue.
data/rules/sa.json	Generated SA regime rules JSON.
data/rules/sa-zatca-v1.json	Generated ZATCA addon rules JSON.
data/rules/tax.json	Generated core tax rules update (adds tax.Note rule entry).
data/rules/bill.json	Generated core bill rules update (tax point/value date constraints, etc.).
data/rules/eu-en16931-v2017.json	Generated EN16931 rules update (VATEX/exemption-note logic changes).
data/rules/es-tbai-v1.json	Generated TBAI rules update (customer guard restructuring).
data/rules/co-dian-v2.json	Generated DIAN rules update (customer guard restructuring).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.