Files
scadaproj/components/ui-theme/validation/theme-1.0.0/exporter.md
T

53 lines
4.9 KiB
Markdown

# TH-08 offline exporter validation
Recorded 2026-11-13 in the managed `scada-ui-consistency/scadaproj` worktree. This record covers the offline implementation only; it does not claim a release-package export, registry import, publication or G1 completion.
## Files
- `ZB.MOM.WW.Theme/build/export-web-assets.py`
- `ZB.MOM.WW.Theme/build/test_export_web_assets.py`
No release version, README, shared ledger, production UI or package artifact was changed by this slice.
## Red → green checks actually executed
Cwd: `ZB.MOM.WW.Theme` in the managed worktree.
```bash
python3 -m unittest discover -s build -p 'test_export_web_assets.py' -v
```
Initial red: unittest failed import with `FileNotFoundError` for the absent `build/export-web-assets.py`. The test file was written before the exporter.
After implementation: **13 unittest methods passed**, with independent synthetic nupkg fixtures and additional negative-case subtests. Following a formatting-only cleanup, the same command passed all 13 again. Runtime: Python 3.14.3. `git diff --check -- build/export-web-assets.py build/test_export_web_assets.py` also passed.
## Behaviors covered
- Byte-for-byte parity for the five specified CSS/font payloads; no DLL or unrelated package payload is exported.
- Exact nuspec package ID, nuspec-derived version, explicit caller-supplied source revision/tag, original nupkg SHA256 and every exported payload SHA256. Manifest excludes a self-hash.
- Complete canonical top-level root tokens including future/custom tokens, raw `var(...)` references, quoted strings and function values. Comments do not create phantom tokens or alter the copied CSS bytes.
- Deterministic zip bytes for identical inputs: sorted paths, fixed timestamps, fixed Unix file metadata, stored compression and stable JSON serialization.
- Changed input CSS bytes change their payload hash and the package provenance hash.
- Refusal of each missing required CSS/font asset; missing/empty required semantic tokens; malformed delimiters, comments/strings/declarations, nested canonical declarations, duplicate root tokens or multiple canonical root blocks.
- Refusal of wrong ID, empty version, malformed/ambiguous nuspec XML; duplicate zip paths; absolute, parent-traversal, Windows-drive/backslash and alias paths, including entries outside the exported allowlist.
- Invalid input leaves existing output intact. Output cannot replace the input nupkg. Successful output uses atomic replacement after complete validation.
- CLI requires all four explicit arguments and creates a valid output archive with valid provenance inputs.
## Parser and provenance boundaries
The parser supports the canonical top-level `:root` custom-property declaration block; it is not a CSS cascade implementation or arbitrary CSS validator. Raw values and references are preserved, not resolved for native consumers. Required semantic tokens include the shared ink/surface/status/accent-family/font contract, so the old pre-1.0.0 package is intentionally not a substitute for the forthcoming reviewed release.
`--source-revision` requires a full Git hash; `--source-tag` requires explicit text such as the actual release tag or an untagged marker. The exporter validates metadata shape but cannot establish that a caller-supplied commit/tag produced the nupkg. The release workflow must supply the reviewed clean package revision and independently verify the exact artifact.
## Remaining TH-08 release checks
Wait for the parent-owned reviewed 1.0.0 nupkg and exact source revision/tag. Then generate `technical-light-web-assets.1.0.0.zip` from those package bytes, independently recompute all payload/source hashes and record both immutable artifact hashes. Registry pilot/import and native mapping belong to their consumer chapters. No real package export was generated in this offline slice.
## Independent-review alias correction
The initial resolved-path equality check missed existing filesystem aliases. Two added regression tests reproduced the defect before the fix: a case alias on this case-insensitive APFS filesystem and a hard link both failed to raise ValueError. The exporter now additionally rejects an existing output whose `Path.samefile(package)` identity matches the input, before reading/writing payloads.
After correction, the same offline unittest command passed **15/15 methods, zero skips** on this host, including both alias regressions and all original integrity cases. Input bytes and aliases remain intact on rejection. The case-alias regression is conditional on filesystem behavior for portability; it actually executed and passed here. Narrow exporter/tests/README `git diff --check` passed. Real-package export/source-revision validation remains deferred to the parent release gate.
Parent integration also made on-accent a required semantic token. Its missing-token subcase reproduced failure before enforcement; all15 artifact tests pass after enforcement. Final source includes this additional release-boundary protection.