beffroi-tools/docs/rust-reporter.md

208 lines
10 KiB
Markdown

# 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
```sh
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](pptx-videos.md).
## 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.
```sh
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](https://proxy.dandaedre.com/gitea/idle-org/rust_realease).
```sh
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:
```sh
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
```
The [upstream packaging task](fix-rust-realease.task.md) specifies the hooks,
runtime-file inclusion and portable artifact support needed to replace this
separate packaging step with the normal `rust_realease` workflow.
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:
```sh
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](https://github.com/BtbN/FFmpeg-Builds#readme)
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](https://ffmpeg.org/download.html).
For another provider or offline packaging, supply a standalone target binary:
```sh
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](https://proxy.dandaedre.com/gitea/Dandaedre/agent-tasks/raw/branch/main/tasks/ci-coverage-badges.task.md).
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:
```sh
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:
```sh
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:
```text
/mnt/assets/coverage/Beffroi/beffroi-tools/main/
```
Public badge URLs:
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/version.svg
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/test.svg
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg
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.