beffroi-tools/docs/rust-reporter.md

9.8 KiB

Rust PPTX reporter trial

The feature/rust-reporter branch ports the reporter only. The Python reporter remains a regression reference; tools/exporter.py is unchanged. The core parses PPTX XML/ZIP, discovers video references in presentation order, extracts/probes media, applies per-shape trims, and writes HTML, Markdown, TXT, JSON, Typst, PDF, dense PDF and Ontime. Defaults remain Markdown + Ontime.

Desktop and CLI

cargo run --locked --bin pptx-reporter-gui
cargo run --locked --bin pptx-reporter -- presentation.pptx --timings-only --report all
cargo run --locked --bin pptx-reporter -- presentation.pptx --extract-only

Drop one PPTX into the window or use the file picker. Choose the output folder, extraction mode and report formats, then Generate. The app remembers options and the last eight presentations. Advanced settings contain overwrite and FFprobe location controls. Result actions open reports/folders and copy file paths. Progress, warnings and an expandable activity log remain visible. Estimates apply to the current counted phase; PDF compilation is an indeterminate step. Cancel interrupts FFprobe and is checked between extraction/report steps; an in-progress Typst compilation finishes before cancellation is observed.

pptx-reporter-gui.exe uses Windows' windowed subsystem (no terminal). pptx-reporter.exe is the CLI; without arguments it also opens the GUI. PDF compilation uses pinned Typst 0.13 crates and bundled DejaVu Sans regular/bold fonts. It reads no external Typst files, downloads no packages and needs no typst.exe. FFprobe is discovered beside the application, under its bin/ directory, or on PATH; --ffprobe PATH overrides discovery.

Output stays in <presentation>_videos/videos and reports. Existing extracted media is reused unless --overwrite is set; reports are regenerated. Empty presentations create no output. Unknown metadata is reported without inventing durations. Loops/custom timing remain visible and are absent from Ontime. Extracted media remains unchanged. See report semantics.

Development and checks

Use a recent stable Rust toolchain and retain Cargo.lock. The desktop build supports X11/Wayland on Linux and Windows. On Linux, windowing/OpenGL libraries must be present at runtime. --no-default-features builds the CLI/core without desktop or PDF dependencies; --features pdf restores embedded PDF generation.

cargo fmt --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --all-features
python3 scripts/parity.py target/debug/pptx-reporter

Parity checks require FFmpeg, FFprobe and the Typst CLI for the Python reference. They build a synthetic presentation with real media, shared clips, distinct trims, loops, invalid/custom timing and orphan media; both implementations must produce identical report JSON and Ontime projects and generate all formats. Visual layouts are deliberately preserved in appearance rather than comparing PDF bytes or requiring identical markup.

Cross and release preparation

Cross.toml configures Windows GNU x64 and Linux GNU x64 with Cross's main images. Linux GNU is intentional for the desktop app; a fully static musl GUI is not promised. Cross needs a working Docker or Podman backend. No release action is run by Jenkins. Release metadata follows the rust_realease contract.

cross build --locked --release --target x86_64-pc-windows-gnu
cross build --locked --release --target x86_64-unknown-linux-gnu
rust_realease . --package pptx-reporter --dry-run
rust_realease . --package pptx-reporter --compile-only

The package metadata matches rust_realease's cargo-binstall archive contract. rust-release.toml maps the SSH origin host to the public HTTPS Gitea repository. Version comes only from Cargo.toml; a future publication needs a matching explicitly created/pushed tag and a clean checkout. Dry-run reports a missing tag as a prerequisite, even while previewing this untagged feature branch. No tag or release is created as part of this trial.

rust_realease archives contain Cargo binaries only. Its current documented configuration has no arbitrary packaging hook. Release automation can call the portable packager after the Cross builds above; it fetches FFprobe on demand:

python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
  --fetch-ffprobe
python3 scripts/package-portable.py --target x86_64-unknown-linux-gnu \
  --fetch-ffprobe

This creates a ZIP under dist/, with both reporter binaries, FFprobe, licences, download provenance, quick-start instructions and a SHA-256 checksum (Linux uses .tar.gz). These commands expect the reporter binaries under target/<target>/release/. rust_realease can use a separate build directory for dirty checkouts; use the explicit Cross commands above for these paths.

The standalone downloader is also callable from a release script:

python3 scripts/fetch_ffprobe.py --target x86_64-pc-windows-gnu

It selects BtbN's FFmpeg 9.0 release-branch, non-shared LGPL builds, checks the archive against the SHA-256 reported by GitHub's release API, and validates PE/ELF format and x86-64 machine type. On a matching host it also runs ffprobe -version before installing the cache entry. Foreign executables are inspected without execution. Downloads are temporary; the extracted binary, upstream notices, and provenance are cached under ignored downloads/ffprobe/<target>/<archive-sha256>/. Cached file hashes are verified on reuse. A failed download/check does not install a cache entry.

The default upstream tag latest moves. For repeatable release builds, pass --ffprobe-release TAG --ffprobe-sha256 HASH to the packager (or --release TAG --sha256 HASH to the downloader). Provenance records the release/asset IDs, download URL and digest. A missing asset or mismatched digest fails rather than silently choosing another build. GitHub API rate limits/network failures are errors; a previously cached download does not bypass metadata verification.

BtbN's compatibility notes specify Windows 10 22H2 or newer, and Linux glibc 2.28/kernel 4.18 or newer. These builds are linked from FFmpeg's download page. For another provider or offline packaging, supply a standalone target binary:

python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
  --ffprobe /path/to/ffprobe.exe --ffprobe-licenses /path/to/notices

No FFprobe binary is committed. Only the downloader and packaging code are versioned; downloads/, target/ and dist/ are ignored. The app/report fonts are already embedded. Do not describe a binary-only rust_realease archive as the complete portable distribution.

A Windows validation machine should check launching without a console, real file drops, file dialogs, Unicode paths, scaling, opening results, and the bundled FFprobe. Building successfully on Linux does not establish those checks. Signing and an installer are optional follow-up distribution work.

Coverage and mutable badges

The workflow implements the coverage-badge task.

CI uses Python 3.11+ for the standard-library TOML reader. Install exactly cargo-llvm-cov 0.9.1 and the active toolchain's llvm-tools-preview. The exact measurement command is:

cargo llvm-cov --locked --all-features --json --summary-only --output-path coverage/summary.json

cargo coverage is an alias for that command. To run the actual gate and diagnostics, use:

python3 scripts/ci.py init
python3 scripts/ci.py coverage
python3 scripts/ci.py finalize

The initial trial floor is 75% line coverage, defined in coverage.toml. The GUI/event loop and both binaries remain in the denominator; there are no production-code exclusions. This is a baseline for the trial, not a claim of complete UI automation. Measurement uses the unrounded covered/count ratio. The temporary coverage/summary.json is removed after diagnostics/badge processing, including on gate failure. Fresh below-floor coverage survives cleanup; unavailable measurements become neutral -%.

Version comes from Cargo.toml. Test status comes only from the current BUILD_NUMBER marker created after Python tests, Rust tests and parity pass. The Jenkins job must be a Multibranch Pipeline providing BRANCH_NAME; the Tools stage enforces its presence. Actual job configuration is an external deployment checkpoint and must be verified by the Jenkins administrator.

Cleanup generates and archives exactly coverage/version.svg, coverage/test.svg, and coverage/coverage.svg with fingerprinting. Only non-PR main builds publish those files under:

/mnt/assets/coverage/Beffroi/beffroi-tools/main/

Public badge URLs:

The renderer comes from Dandaedre/agent-tasks revision 8923682b958de698c5ec41f4275bfc6f7e44a2f6. Generated badges, markers and summaries are ignored. Tests exercise renderer validation/XML, threshold boundaries, failure cleanup, publication permissions and old-branch-symlink migration.

The external asset server should mount published assets read-only, disable directory listings, serve SVG with a restrictive CSP, and revalidate mutable URLs or give them a short cache lifetime. Live publication and public retrieval must be verified separately; adding README URLs does not make badges live.