Skip to content

refactor: replace Python domain utilities with isolated PHP tooling - #97

Merged
vitormattos merged 28 commits into
mainfrom
refactor/php-domain-tools
Oct 8, 2026
Merged

vitormattos merged 28 commits into
mainfrom
refactor/php-domain-tools

Conversation

@vitormattos

@vitormattos vitormattos commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

Objective

Use PHP-only tooling to maintain official NFS-e annex snapshots and NT009 source evidence, without loading PhpSpreadsheet in production. The NT009 evidence changes from the former PR #99 have been merged into this feature branch; this PR has not been merged into main.

PHP version policy (review follow-up)

  • Root composer.json is the single version-policy source: require.php defines the minimum library compatibility, while extra.ci.php-matrix and extra.ci.php-default define deliberate CI coverage and its primary PHP version.
  • tools/bin/ci-php.php exposes minimum, matrix, primary, validate, and assert-runtime without dependencies.
  • .github/actions/setup-project-php resolves the minimum from Composer; the PHPUnit job derives its dynamic strategy matrix and coverage/integration version from that policy.
  • All eight PHP-configuring workflows use the local action: no hard-coded php-version: "8.x" remains in workflow YAML.
  • The isolated vendor-bin/domains/composer.json no longer duplicates the PHP version; Composer install/update hooks validate the interpreter against the root constraint. The isolated lockfile was regenerated without changing any of the 33 locked package versions.

Official-source CLI and testability

  • tools/bin/domains.php download --ids=... --output=... replaces the long embedded PHP downloader in Official Snapshot Reproduction.
  • tools/bin/domains.php verify-indicators --annex-vii=... replaces the long embedded PHP verifier in NT009 Source Evidence.
  • Both workflows now orchestrate CLI commands, not handwritten business logic.
  • OfficialAnnexDownloader rejects non-official URLs, incorrect IDs, missing/bad observed SHA-256 values, changed bytes and HTML masquerading as XLSX before writing output. Fetching is injectable for offline PHPUnit tests.
  • Nt009Inspector::verifyIndicatorSnapshot() checks exact Annex VII triplets, cardinality, duplicates and order against the original government workbook; exercised via offline fixtures.
  • The existing domain-tables, source-watch and audit commands still operate under the same isolated PhpSpreadsheet installation.
  • The new PHP-version and official-source code is PHPUnit-tested, with negative cases for policy drift, unsupported runtimes, duplicate IDs and bad checksums.

Original deliverables retained

  • Replaced Python generator and tests with PHP, PHPUnit, and isolated PhpSpreadsheet; existing runtime OfficialDomainCatalog, XSD, XML generation and downstream consumer are not changed.
  • All five production TSVs reproducibly regenerate byte-for-byte from the official Anexos A/B/C.
  • Official source hashes and version index detection are recorded in resources/domains/sources.json.
  • The additional frozen NT009 Annex VII v1.03.00 snapshot preserves all 40 published indicators separately from the 26-code production Anexo C, without enabling new tax semantics.
  • Read-only official source and NT009 evidence workflows keep reports/XLSX artifacts; publication does not imply production schema activation.

Validation

The root and isolated composer.json files pass composer validate --strict. The isolated PHPUnit suite, PHP syntax checks, linting, static analysis, minimum-dependency tests, REUSE and commit conventions passed on the updated branch. The actual (not merely advisory workflow-level) Official Snapshot Reproduction and NT009 Source Evidence jobs also succeeded, reproducing the five production snapshots and verifying all 40 Annex VII triplets against government XLSX files.

On commit da6cd5d91926b84cd1de31ba90b4956bf6dbbf3c, eight of nine workflows passed. The full application PHPUnit workflow remains pending because another older PHPunit workflow run is still active. Do not treat the PR as fully green until that check finishes; inspect the live status before merging. All eight commits in this CI refactor were individually verified as cryptographically signed and DCO-compliant.

Deliberate exclusions

No merge is requested, and this PR does not claim that NT009 is effective for production issuance. The activation dates, XML contract and conditional tax rules still need their own review before issue #95 is complete.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…PHPUnit

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…rences

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
@vitormattos
vitormattos marked this pull request as ready for review October 8, 2026 22:26
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…risons

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
vitormattos and others added 9 commits October 8, 2026 22:32
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…lization

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
feat: audit official NT009 indicators and layout evidence in PHP (#95)
…ifest

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
… matrix

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…ot verification services

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…oling

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
…aint

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
@vitormattos
vitormattos merged commit 1cc8319 into main Oct 8, 2026
15 checks passed
@vitormattos
vitormattos deleted the refactor/php-domain-tools branch October 8, 2026 23:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant