Validation & Build Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Validation and build scripts enforce repository policy and manage the lifecycle of the Spotty playback engine. These scripts partition verification into Rust and Swift lanes, ensuring that formatting, ABI signatures, and artifact integrity meet project standards before promotion to a release candidate.
The main entry point for local verification is Scripts/check.sh, which orchestrates formatting checks, Rust backend testing, and Swift application compilation. Specialized Python scripts handle complex tasks like dependency license generation and CI artifact promotion.
Core Validation Gate (check.sh)
Scripts/check.sh serves as the primary enforcement tool for the repository. It validates the entire project or specific sub-components based on environment variables.
Verification Scopes
The script supports three execution scopes defined by the SPOTTY_CHECK_SCOPE variable:
- full: Executes all policy, Rust, and Swift checks.
- rust: Limits verification to the Rust playback engine, including formatting, clippy, and unit tests.
- swift: Limits verification to the Swift application, ABI signature checks, and SwiftPM tests.
Sources: Scripts/check.sh:11-25, Scripts/AGENTS.md:9-12
Validation Flow
The following diagram illustrates the sequential checks performed by check.sh during a full verification run:
This diagram shows the high-level execution order of verification tasks in check.sh.
Sources: Scripts/check.sh:31-285
Playback Engine Build & XCFramework Management
The project encapsulates its Rust-based playback engine within an Apple XCFramework. This process involves building static libraries, generating C headers, and validating the resulting artifacts.
Build Orchestration
Backend/spotty-playback/build-xcframework.sh automates the creation of the SpottyPlaybackCore.xcframework. It performs the following actions:
- Calculates a
source_digestusingsource-input-digest.shto track input changes. - Compiles the Rust code into a static library for
arm64-apple-darwin. - Generates licensing notices using
Scripts/generate-playback-notices.py. - Packages the library, headers, and metadata into a zip archive with stable checksums.
Sources: Backend/spotty-playback/build-xcframework.sh:45-80, Backend/spotty-playback/build-xcframework.sh:140-160
XCFramework Validation
Backend/spotty-playback/validate-xcframework.sh ensures the integrity of the built artifact. It enforces strict requirements on the framework structure and metadata:
| Check Category | Requirement |
|---|---|
| Minimum OS | macOS 15.0 |
| Architecture | arm64 only |
| Library Type | Static |
| Headers | Must contain spotty_playback.h and module maps |
| Mach-O | Validates LC_BUILD_VERSION via otool |
Sources: Backend/spotty-playback/validate-xcframework.sh:58-85, Backend/spotty-playback/validate-xcframework.sh:116-135
CI Candidate Promotion
The Scripts/playback_promotion.py script promotes CI artifacts to release candidates without executing untrusted code from the archive.
Promotion Requirements
For a candidate to be promoted, it must meet several cryptographic and environmental conditions:
- Repository Match: The candidate must originate from the official repository, not a fork.
- CI Success: Specific jobs ("Rust checks", "Candidate Swift debug", "Candidate Swift release") must have succeeded.
- Provenance: The
source-provenance.txtandspotty_playback_provenance.jsonmust match the reviewed source SHA. - Workflow Integrity: The CI definition in the candidate must match the trusted publisher's workflow.
Sources: Scripts/playback_promotion.py:34-50, Scripts/playback_promotion.py:73-100
This diagram outlines the communication between the promotion script and the GitHub API to verify artifact safety.
Sources: Scripts/playback_promotion.py:125-155
Licensing and Metadata Generation
The project uses Scripts/generate-playback-notices.py to manage transitive dependencies in the Rust backend. This script requires Python 3.11 for its native TOML parsing capabilities.
Generation Logic
- Dependency Graph: It executes
cargo treeandcargo metadatato identify every third-party crate in the playback engine. - License Discovery: It searches crate directories for common legal files (LICENSE, NOTICE, etc.).
- Override Management: If a license is missing, it applies manual overrides defined in
Scripts/playback-license-overrides.json. - Manifest Creation: It outputs a
manifest.jsoncontaining SHA-256 hashes of every license text and its package association.
Sources: Scripts/generate-playback-notices.py:25-45, Scripts/generate-playback-notices.py:465-510
Auxiliary Build Utilities
Size Reporting
Scripts/report-size.sh provides visibility into the impact of changes on the binary footprint. It generates a Markdown table and a size-report.json file.
- Metrics: Reports app binary bytes, XCFramework archive size, and Mach-O segment sizes (__TEXT, __DATA, __LINKEDIT).
- Symbol Counting: Uses
nm -gUto count exported symbols in the playback archive to prevent silent growth of the ABI surface.
Sources: Scripts/report-size.sh:110-140, Scripts/report-size.sh:185-210
ABI Signature Verification
Within check.sh, the system verifies the C ABI between Rust and Swift. It uses clang to parse headers and compares them against a signature fixture.
- Symbol Match: Compares symbols exported by the static library (via
nm) with declarations in the C header. - Type Safety: Generates
_Static_assertstatements using__builtin_types_compatible_pto ensure that C function signatures match theabi-signatures.txtfixture.
Sources: Scripts/check.sh:100-125, Scripts/check.sh:140-165
Conclusion
The Spotty build system prioritizes fail-fast verification and artifact provenance. By partitioning checks and enforcing strict ABI and licensing contracts, the scripts ensure that the experimental playback engine remains stable and compliant throughout the development lifecycle.