Organize Rust workspace and finalize CI and documentation

This commit is contained in:
Dandaedre 2026-10-20 14:33:56 +02:00
parent ac5d586099
commit 534cce41cd
38 changed files with 321 additions and 724 deletions

View File

@ -1,2 +1,2 @@
[alias]
coverage = "llvm-cov --locked --all-features --json --summary-only --output-path coverage/summary.json"
coverage = "llvm-cov --locked --workspace --all-features --json --summary-only --output-path coverage/summary.json"

View File

@ -1,12 +1,12 @@
# beffroi-tools
This repository contains a Rust PPTX reporter trial and Python command-line tools
This repository contains a Rust PPTX reporter and Python command-line tools
for everyday local document and media workflows. Keep them simple to run. Keep `README.md` minimal,
with quick-start examples and links to detailed documentation in `docs/`.
## Current tools
- `src/` is the Rust reporter: shared core, CLI and egui desktop interface.
- `crates/pptx-reporter/` is the Rust reporter: shared core, CLI and egui desktop interface.
PDF compilation and DejaVu fonts are embedded. Discover FFprobe beside the app,
under `bin/`, or on PATH. Keep report/JSON/Ontime behavior compatible with the
Python reference; `scripts/parity.py` verifies real-media parity.
@ -44,6 +44,14 @@ with quick-start examples and links to detailed documentation in `docs/`.
ignored `downloads/`. Portable release packaging calls it with
`--fetch-ffprobe`; include upstream notices/provenance, never commit binaries.
## Repository layout
- `tools/` and `tests/`: Python prototypes and their regression tests.
- `crates/<tool>/`: each Rust port owns its source, assets, build script and tests.
- Root Cargo workspace: shared version/metadata, lockfile, profiles and target directory.
- Keep Python references while parity is useful; add future Rust tools as workspace
members and include every member in CI checks and coverage.
## Working conventions
- Prefer Python's standard library and existing external CLI tools over adding
@ -62,9 +70,9 @@ with quick-start examples and links to detailed documentation in `docs/`.
`python3 -m unittest discover -s tests -v`. For rendering changes,
test with the actual external tools when available and inspect visual output.
Report any checks that could not be completed.
- Rust gates: `cargo fmt --check`, `cargo clippy --locked --all-targets
--all-features -- -D warnings`, `cargo test --locked --all-features`, and
`RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps`.
- Rust gates: `cargo fmt --all --check`, `cargo clippy --locked --workspace --all-targets
--all-features -- -D warnings`, `cargo test --locked --workspace --all-features`, and
`RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps`.
Run `python3 scripts/ci.py coverage` for the whole Rust application; do not
exclude production GUI/PDF code to raise the reported percentage.

View File

@ -1,49 +1,14 @@
[package]
name = "pptx-reporter"
[workspace]
members = ["crates/pptx-reporter"]
default-members = ["crates/pptx-reporter"]
resolver = "3"
[workspace.package]
version = "0.1.0"
edition = "2024"
license = "MIT"
description = "Local PPTX video timing reports with a drag-and-drop desktop interface"
repository = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
[features]
default = ["desktop", "pdf"]
desktop = ["dep:eframe", "dep:rfd", "dep:directories", "dep:open"]
pdf = ["dep:typst", "dep:typst-pdf"]
[dependencies]
anyhow = "1"
clap = { version = "4", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
zip = { version = "2", default-features = false, features = ["deflate"] }
roxmltree = "0.20"
tempfile = "3"
uuid = { version = "1", features = ["v5"] }
eframe = { version = "0.31", optional = true, default-features = false, features = ["default_fonts", "glow", "x11", "wayland"] }
rfd = { version = "0.15", optional = true }
directories = { version = "6", optional = true }
open = { version = "5", optional = true }
typst = { version = "0.13.1", optional = true }
typst-pdf = { version = "0.13.1", optional = true }
[build-dependencies]
winresource = "0.1.17"
[[bin]]
name = "pptx-reporter"
path = "src/main.rs"
[[bin]]
name = "pptx-reporter-gui"
path = "src/bin/gui.rs"
required-features = ["desktop"]
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz"
pkg-fmt = "tgz"
bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
[profile.dev]
debug = 0

10
Jenkinsfile vendored
View File

@ -43,9 +43,9 @@ pipeline {
steps {
sh '''
set -eu
cargo fmt --check
cargo clippy --locked --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
'''
}
}
@ -55,8 +55,8 @@ pipeline {
sh '''
set -eu
python3 -m unittest discover -s tests -v
cargo test --locked --all-features
cargo build --locked --all-features
cargo test --locked --workspace --all-features
cargo build --locked --workspace --all-features
python3 scripts/parity.py target/debug/pptx-reporter
python3 scripts/ci.py tests-passed
'''

View File

@ -4,33 +4,21 @@
![test status](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/test.svg)
![line coverage](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg)
Local document and media tools. This branch trials a Rust PPTX reporter with a
drag-and-drop desktop app, embedded PDF generation, and the existing CLI formats.
Local document and media tools: a Rust PPTX video reporter with a drag-and-drop
app, and Python tools for prototyping and document exports.
```sh
cargo run --locked --bin pptx-reporter-gui
cargo run --locked --bin pptx-reporter -- presentation.pptx --report all
```
Video timings need FFprobe (from FFmpeg); PDF generation is built in.
The Python reference and document exporter remain available (Python 3.9+):
```sh
# Extract videos with Markdown + Ontime reports (requires ffprobe).
python3 tools/pptx_videos.py presentation.pptx
# Export slides to PDF and PNG images (requires DeckCraft).
python3 tools/exporter.py presentation.pptx --output pdf,images
# Render PDF pages as PNG images (requires PdfCraft).
python3 tools/exporter.py document.pdf --output images
```
- [Video reports](docs/pptx-videos.md) — formats, extraction modes, and dependencies.
- [Document exports](docs/exporter.md) — image resolution, AppImages, and output options.
- [Development and CI](docs/development.md) — layout, tests, and Jenkins setup.
- [Rust reporter](docs/rust-reporter.md) — desktop usage, Windows/Cross builds,
portable packaging, release preparation, and coverage.
- [Trial task list](docs/rust-reporter-tasks.md) — progress and verification.
The reporter needs FFprobe (included in portable bundles); PDF generation is
built in. The exporter needs DeckCraft for PPTX or PdfCraft for PDF input.
Run source commands from the repository root; CLI tools support `--help`.
Run commands from the repository root. Each tool supports `--help`.
- [Reporter](docs/rust-reporter.md) · [Windows quick start](docs/windows-quickstart.txt)
- [Report options and Python reference](docs/pptx-videos.md)
- [Document exports](docs/exporter.md)
- [Development](docs/development.md) · [CI and coverage](docs/ci.md)
- [Cross builds and portable releases](docs/releases.md)

View File

@ -1,5 +1,5 @@
# Whole Rust application, including desktop and PDF code; no production exclusions.
# Trial baseline: the native window/event loop still needs Windows GUI automation.
# Whole Rust workspace, including desktop and PDF code; no production exclusions.
# Baseline: the native window/event loop still needs Windows GUI automation.
line-floor = 75.0
tool = "cargo-llvm-cov"
tool-version = "0.9.1"

View File

@ -0,0 +1,45 @@
[package]
name = "pptx-reporter"
version.workspace = true
edition.workspace = true
license.workspace = true
description = "Local PPTX video timing reports with a drag-and-drop desktop interface"
repository.workspace = true
[features]
default = ["desktop", "pdf"]
desktop = ["dep:eframe", "dep:rfd", "dep:directories", "dep:open"]
pdf = ["dep:typst", "dep:typst-pdf"]
[dependencies]
anyhow = "1"
clap = { version = "4", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
zip = { version = "2", default-features = false, features = ["deflate"] }
roxmltree = "0.20"
tempfile = "3"
uuid = { version = "1", features = ["v5"] }
eframe = { version = "0.31", optional = true, default-features = false, features = ["default_fonts", "glow", "x11", "wayland"] }
rfd = { version = "0.15", optional = true }
directories = { version = "6", optional = true }
open = { version = "5", optional = true }
typst = { version = "0.13.1", optional = true }
typst-pdf = { version = "0.13.1", optional = true }
[build-dependencies]
winresource = "0.1.17"
[[bin]]
name = "pptx-reporter"
path = "src/main.rs"
[[bin]]
name = "pptx-reporter-gui"
path = "src/bin/gui.rs"
required-features = ["desktop"]
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz"
pkg-fmt = "tgz"
bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"

View File

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 76 KiB

View File

Before

Width:  |  Height:  |  Size: 364 KiB

After

Width:  |  Height:  |  Size: 364 KiB

View File

Before

Width:  |  Height:  |  Size: 1.3 MiB

After

Width:  |  Height:  |  Size: 1.3 MiB

68
docs/ci.md Normal file
View File

@ -0,0 +1,68 @@
# CI and coverage
Jenkins must use a Multibranch Pipeline supplying `BRANCH_NAME`, with the
`rust_no_docker` worker, Python 3.11+, Rust, FFmpeg/FFprobe and the Typst CLI.
SCM credentials, webhooks and the publication mount are administrator setup.
CI checks formatting, Clippy, rustdoc, Python/Rust tests, real-media parity and
whole-workspace Rust coverage. It never creates tags or release artifacts.
## Measurement
CI installs pinned `cargo-llvm-cov 0.9.1` and `llvm-tools-preview`. The tracked
`.cargo/config.toml` alias `cargo coverage` expands to:
```sh
cargo llvm-cov --locked --workspace --all-features --json --summary-only --output-path coverage/summary.json
```
Run the same lifecycle locally (no publication):
```sh
python3 scripts/ci.py init
python3 scripts/ci.py coverage
python3 scripts/ci.py finalize
```
The enforced floor is **75% line coverage**, configured in `coverage.toml`.
Ordinary production code, GUI and PDF code remain included. The gate compares
unrounded covered/count totals, logs the measurement and floor before PASS/FAIL,
and retains tool failure status even when a valid measurement exists.
`init` removes stale output. CI creates `.tests-passed-${BUILD_NUMBER}` only
after all required tests and parity pass. A valid measurement creates
`.coverage-ready-${BUILD_NUMBER}` even below the floor. Cleanup preserves that
measurement; unavailable coverage becomes neutral `-%`. Temporary
`coverage/summary.json`, diagnostics and markers are deleted after processing.
Generated badges and reports are ignored, never committed.
## Badges
In `post { cleanup }`, Jenkins reads the version from root
`Cargo.toml` → `workspace.package.version`, renders current-build status, and
archives exactly these files with fingerprints and `allowEmptyArchive: false`:
- `coverage/version.svg`
- `coverage/test.svg`
- `coverage/coverage.svg`
Only non-PR `main` builds publish, including failed builds, under
`/mnt/assets/coverage/Beffroi/beffroi-tools/main/`. The POSIX publication script
validates sources and destination components, writes atomically and never
synchronizes or prunes the shared mount.
Public URLs (also referenced once each below the README title):
- 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 matches the maintained script from `Dandaedre/agent-tasks`,
revision `8923682b958de698c5ec41f4275bfc6f7e44a2f6`, rechecked against the
[coverage task](https://proxy.dandaedre.com/gitea/Dandaedre/agent-tasks/raw/branch/main/tasks/ci-coverage-badges.task.md).
`tests/test_ci_badges.py` covers threshold boundaries, tool failures, missing
measurements, SVG validation and safe publication to temporary directories.
Actual Jenkins archival/publication and public URL retrieval are separate
external checkpoints. Local checks do not establish that badges are live.
The asset server should mount assets read-only, disable listings, serve SVG
with restrictive CSP, and revalidate mutable URLs or use a short cache lifetime.

View File

@ -1,33 +1,47 @@
# Development and CI
# Development
`tools/` contains the Python tools, `src/` the Rust reporter trial, `tests/`
both regression suites, and `scripts/` parity, packaging and badge utilities.
Keep specialized documentation in `docs/` and quick starts in the README.
## Layout and workflow
Run Python checks from the repository root:
| Directory | Purpose |
| --- | --- |
| `tools/` | Python prototypes and document utilities |
| `tests/` | Python regression and CI/packaging tests |
| `crates/<tool>/` | Rust ports, each with its own source, tests and assets |
| `scripts/` | Shared CI, parity and release helpers |
| `docs/` | Tool usage and specialized workflows |
Prototype in Python, then add a Rust workspace member when the workflow is
stable. Keep the Python implementation as a parity reference while useful.
Avoid speculative shared crates; extract common code when multiple tools need it.
The root `Cargo.toml` owns workspace metadata, the shared version and build
profiles. Members inherit that metadata. Keep one root `Cargo.lock` and `target/`.
The reporter is the default member; CI explicitly checks the entire workspace.
Use `-p pptx-reporter` to select it when building from a multi-tool workspace.
## Checks
Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+.
Run from the repository root:
```sh
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --workspace --all-features
python3 scripts/parity.py target/debug/pptx-reporter
```
Those tests mock external document tools. The Rust trial additionally runs
real-media parity with FFmpeg, FFprobe and the Typst CLI. It checks identical
JSON/Ontime output and generates all report formats. See the
[Rust development commands and coverage contract](rust-reporter.md).
Parity requires FFmpeg, FFprobe and the Typst CLI for the Python reference.
It compares JSON/Ontime for real media with trims, loops, custom timing and
orphan media, and generates every report format. Python exporter tests mock
external document applications. Inspect rendering changes visually as well.
The Jenkins Multibranch Pipeline uses `rust_no_docker`, Python 3.11+, Rust,
FFmpeg/FFprobe and Typst. It checks formatting, Clippy, documentation, Python
and Rust tests, parity, and measured Rust line coverage. It installs pinned
`cargo-llvm-cov` when needed. Cross/container builds happen outside Jenkins.
`cargo build -p pptx-reporter --no-default-features` builds the CLI without the
GUI or PDF engine; add `--features pdf` to restore embedded PDFs.
Cleanup archives the three version/test/coverage badges. Only non-PR `main`
builds publish these mutable SVGs to the configured asset mount. Jenkins never
creates tags or releases and does not archive release binaries.
The administrator must configure the actual Multibranch job, SCM credentials,
worker dependencies and publication mount. For a Gitea-aware job, the webhook
endpoint is the Jenkins base URL plus `/gitea-webhook/post`, with push events
enabled. This repository does not create jobs, credentials or webhooks.
Every task that changes repository files ends with a commit after relevant
checks; no push unless requested. Keep generated outputs out of Git.
Keep generated files out of Git. Commit each completed task after checks; do
not push without authorization. See [CI and coverage](ci.md) and
[cross builds and packaging](releases.md).

View File

@ -1,331 +0,0 @@
# Task: support complete portable application bundles in rust_realease
## Objective
Extend [rust_realease](https://proxy.dandaedre.com/gitea/idle-org/rust_realease)
so a single release invocation can build a Rust application, prepare its
target-specific runtime dependencies, assemble complete portable archives,
and checksum, publish and verify those archives through the normal workflow.
This is generic release packaging functionality. Do not hard-code FFmpeg,
BtbN, this application, or its target list into the release tool.
Project-specific dependency acquisition may remain a small script; archive
creation, build-output discovery and publication must belong to rust_realease.
This document is an implementation specification for the upstream repository,
not a request to publish a release or change this project's CI into a publisher.
Inspect upstream code and instructions before implementing. The configuration
and hook protocol below are **proposed APIs**, not existing supported options.
Equivalent naming is acceptable if all behavioral requirements are met.
## Observed baseline and concrete problem
The consumer is `pptx-reporter` in
[Beffroi/beffroi-tools](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools),
on `feature/rust-reporter`. The locally tested publisher is
`rust_realease 0.1.6-rc.2`. The current
[advanced usage documentation](https://proxy.dandaedre.com/gitea/idle-org/rust_realease/src/branch/main/docs/advanced-usage.md)
was checked on 2026-10-20. Distinguish that installed version from upstream main;
reuse any capabilities that have landed since, rather than implementing them twice.
The reporter has two Cargo binaries, `pptx-reporter` and `pptx-reporter-gui`.
It embeds Typst and fonts, but invokes an external `ffprobe` executable.
Windows users should extract an archive and double-click the GUI with no Python,
Typst, PowerPoint or separate FFmpeg installation. Python may be a build-host
dependency for a configured preparation script.
Current gaps:
- The documented release archives contain the package's declared Cargo binaries.
They do not provide a documented mechanism for runtime executables, notices,
templates, README files or other application resources.
- The documented formats are `tgz`, `binary` and `both`. Windows desktop users
need an ordinary ZIP as well as the existing cargo-binstall distribution.
- Cross `pre-build` prepares a container image/build environment. It is not a
packaging hook with access to completed binaries and target bundle staging.
- A dirty checkout may build in a fresh, publisher-owned target directory.
A project packager cannot safely assume `target/<triple>/release/<binary>`.
- A successful cargo-binstall check of the declared Rust binaries does not by
itself establish that adjacent runtime executables/resources are installed.
The workaround lives in this consumer repository:
- `scripts/fetch_ffprobe.py`: download a target build, check its SHA-256 and
PE/ELF architecture, retain notices/provenance, cache outside Git, and perform
a native version check when possible.
- `scripts/package-portable.py`: independently locate Cargo outputs, copy the
dependency and notices, produce Windows ZIP/Linux tar.gz and checksum files.
- `rust-release.toml`: currently documents calling that packager separately.
Replace the second script's responsibilities with upstream support. Keep
provider-specific download logic reusable through a thin preparation adapter.
## Required application layout
Produce these portable distributions for the currently supported targets:
| Target | Format | Runtime dependency |
| --- | --- | --- |
| `x86_64-pc-windows-gnu` | ZIP | `ffprobe.exe`, built for Windows x86-64 |
| `x86_64-unknown-linux-gnu` | tar.gz/tgz | `ffprobe`, built for Linux x86-64 |
Each archive has one predictable root directory:
```text
pptx-reporter-portable-<target>-v<version>/
pptx-reporter[.exe]
pptx-reporter-gui[.exe]
ffprobe[.exe]
README.txt
LICENSES/
reporter-MIT.txt
DejaVu.txt
ffmpeg/
<upstream notices>
provenance.json
```
Executable permissions must survive Linux extraction. Windows executable names
must have `.exe`. Do not accidentally bundle the host's FFprobe, unrelated
FFmpeg programs, build caches or source checkout. Allow explicitly declared DLLs,
shared libraries and resource directories for applications that need them;
this project's selected FFprobe distributions do not need separate FFmpeg DLLs.
## Required capabilities
### 1. Declarative bundles alongside existing artifacts
Support named bundles with target filters, per-target archive formats, a root
directory/name template, Cargo binary selection, and explicit extra files or
directory trees with destination paths inside the bundle.
Existing configurations must retain their current behavior. Existing
`package.format`, `--artifact-format`, archive names and cargo-binstall metadata
must keep their existing meanings; named bundles are additional artifacts.
Reject unknown or inconsistent configuration rather than silently ignoring it.
If a selected bundle lacks a format for a selected target, fail clearly.
`--target` must also filter hooks, dependency fetches and bundle creation.
Illustrative configuration for this consumer:
```toml
[package]
format = "tgz" # Keep the existing cargo-binstall artifacts.
[[package.bundles]]
name = "portable"
targets = ["x86_64-pc-windows-gnu", "x86_64-unknown-linux-gnu"]
formats = { x86_64-pc-windows-gnu = "zip", x86_64-unknown-linux-gnu = "tgz" }
archive-name = "{name}-portable-{target}-v{version}"
root = "{name}-portable-{target}-v{version}"
cargo-binaries = "all"
files = [
{ source = "LICENSE", destination = "LICENSES/reporter-MIT.txt" },
{ source = "assets/fonts/LICENSE", destination = "LICENSES/DejaVu.txt" },
{ source = "docs/windows-quickstart.txt", destination = "README.txt" },
]
[package.bundles.prepare]
command = ["python3", "scripts/prepare-release.py", "--context", "{context-file}", "--manifest", "{manifest-file}"]
inputs = ["scripts/prepare-release.py", "scripts/fetch_ffprobe.py"]
timeout-seconds = 600
required-destinations = ["ffprobe{binary-ext}", "LICENSES/ffmpeg/LICENSE.txt", "LICENSES/ffmpeg/provenance.json"]
```
`prepare-release.py` above is a proposed thin adapter, not an existing file.
It would call this project's downloader and return the prepared file list.
Define whether static source paths are package- or workspace-relative; default
to package-relative and provide an explicit workspace-relative form.
This must work for selected members of Cargo workspaces.
In templates, `{name}` is the Cargo package name, `{bundle}` is the bundle name,
and `{binary-ext}` is the target suffix. Append the selected archive format's
extension to `archive-name`; do not reinterpret it as a filesystem source path.
### 2. A host-side preparation hook with a stable contract
Run preparation once per selected bundle/target, after successful compilation
and before archive creation, checksums, release creation or uploads. This is
packaging work on the host, not a command inside a Cross build container.
Use an argument vector, not implicit shell interpolation. Explicit shell use
can be configured as `["sh", "..."]`. Define the working directory and supply a
versioned JSON context file containing:
- Package name/version, target triple, profile and target executable suffix.
- Workspace and selected package roots, and the source commit/dirty state.
- An exact mapping of declared binary names to **actual built executable paths**.
- Fresh hook output/staging directory, persistent cache directory, and result
manifest path, all absolute.
- Bundle name and protocol version.
Resolve binary paths from actual build artifacts or the validated build cache.
Do not reconstruct them from a conventional target directory. Support
`CARGO_TARGET_DIR`, publisher-owned fresh build directories, non-default profiles
and workspace members.
The hook writes only its outputs into its supplied output directory and emits
a manifest. For example:
```json
{
"schema_version": 1,
"target": "x86_64-pc-windows-gnu",
"files": [
{
"source": "ffprobe.exe",
"destination": "ffprobe.exe",
"kind": "executable",
"sha256": "<actual 64-character SHA-256>"
},
{
"source": "notices/provenance.json",
"destination": "LICENSES/ffmpeg/provenance.json",
"kind": "file",
"sha256": "<actual 64-character SHA-256>"
},
{
"source": "notices/LICENSE.txt",
"destination": "LICENSES/ffmpeg/LICENSE.txt",
"kind": "file",
"sha256": "<actual 64-character SHA-256>"
}
]
}
```
Paths in that manifest are relative to the hook output directory and bundle
root respectively. The publisher validates them, copies only declared files,
checks the recorded hashes, and owns final archive construction. Static inputs
and Cargo binaries are also hashed and included in an artifact manifest.
Stream hook output with target/bundle labels. Identify the failing command and
exit status. Stop on nonzero exit, timeout, cancellation, missing required
outputs, invalid manifest or hash mismatch. Clean temporary staging and do not
create/upload a partial release. Terminate hook subprocesses on cancellation.
Do not pass Gitea tokens or publication credentials into hooks; preserve the
existing child-process credential isolation.
### 3. Runtime dependency integrity and caching
A hook can download dependencies into the supplied persistent cache; it must
not need tracked binaries or tracked generated outputs. Allow explicit digest
pins and immutable release identifiers through declared configuration/inputs.
For this consumer, continue using verified target-specific non-shared LGPL
FFprobe builds. Preserve their upstream notices and provenance, including
provider URL, release/asset IDs, archive SHA-256 and extracted file hashes.
Do not make a provider-specific built-in downloader a prerequisite for this fix.
Keep build-cache reuse separate from bundle preparation. Reusing valid Rust
executables must not accidentally reuse stale auxiliary files. A straightforward
first implementation can rerun preparation for each packaging invocation while
the hook reuses its own checksum-verified download cache.
If prepared bundles themselves are cached, fingerprint the effective bundle
configuration, hook command and declared inputs, static file contents, actual
binary hashes, and resolved dependency identities/hashes. Changes in a moving
`latest` dependency must be resolved before accepting a bundle cache hit.
Do not treat an unchanged Git commit as proof of identical runtime dependencies.
### 4. Validate and package all files consistently
Reject absolute destinations, `..`, destination collisions, duplicate entries,
symlinks/hardlinks escaping approved roots, device files and missing required
inputs. For Windows bundles also reject case-insensitive destination collisions
and invalid/reserved Windows destination names. Hooks cannot replace a declared
Cargo executable by writing another file to its destination.
Check target architecture/format for declared runtime executables. A foreign
executable must not be run on the build host merely because packaging succeeded.
Allow an explicit native smoke-test command; record passed, failed and skipped
checks distinctly. Cross-compilation is not Windows runtime validation.
Produce archives atomically with deterministic ordering, normalized ownership,
timestamps and permissions, preserving the intended executable bits. Identical
inputs should produce identical archives. Avoid leaking absolute host paths or
environment secrets into generated public manifests.
### 5. Integrate bundles into the complete release lifecycle
- `--dry-run`: validate configuration and show bundle formats, target selections,
static inclusions, hook commands and declared required outputs. Do not execute
hooks, fetch dependencies or produce archives. Mark dynamic results unresolved.
- `--compile-only` and `--stop-after package`: build/reuse binaries, run preparation
and produce complete local bundles and checksums. No Gitea token, release,
tag creation or push is required.
- `--skip-tests`: skip the existing test phase only; do not bypass hook success,
file/hash checks or archive validation.
- Normal publication: finish and validate **all** requested artifacts before
release creation/upload. Include named bundles in the existing `SHA256SUMS`,
collision handling, `--replace-assets` and post-upload download verification.
Keep existing draft/prerelease behavior and do not delete unrelated assets.
- Print every resulting artifact path and its checks performed/skipped. Provide
a machine-readable artifact manifest so consumers do not scrape console output.
- Fail before remote mutations if any bundle fails. Do not promise transactional
rollback of remote uploads where the existing backend cannot provide it.
### 6. Preserve the cargo-binstall contract
Keep the existing canonical `{name}-{target}-v{version}.tgz` archives and their
metadata/install checks working. Portable archives use distinct names, for
example `{name}-portable-{target}-v{version}.zip`, avoiding ambiguous asset matches.
Do not assume extra files in an archive become installed beside Cargo binaries
by cargo-binstall. Verify its actual behavior before promising that. For this
consumer the supported baseline is:
- The portable bundle contains everything and is validated as a complete tree.
- The cargo-binstall installation still installs the declared Rust binaries.
Its usage documentation explicitly states the remaining external FFprobe
requirement unless runtime-dependency installation is actually implemented
and tested end to end.
Archive verification must understand the selected artifact's declared contents,
not reject a valid portable bundle for containing more than Cargo binaries.
## Tests and acceptance criteria
Use local fixture hooks/downloads and small fixture binaries in automated tests;
do not depend on mutable GitHub releases or download hundreds of MB per test.
- [ ] Legacy configurations produce unchanged artifact names, layout and
cargo-binstall behavior, including multiple binaries.
- [ ] A fixture hook receives correct target/version/profile, source roots and
real executable paths for clean, dirty, cached and custom-target-dir builds.
- [ ] The Windows ZIP and Linux tar.gz contain both application binaries, a
target-matching FFprobe fixture, README and license/provenance files.
- [ ] Target filtering does not run hooks or fetch dependencies for other targets.
- [ ] Nonzero exit, timeout/cancellation, missing executable/license, bad hashes,
malformed manifests and architecture mismatches prevent publication.
- [ ] Traversal, escaping links, duplicate/case-colliding destinations, reserved
Windows names and attempts to replace Cargo binaries are rejected.
- [ ] Paths with spaces and Unicode are handled without shell reinterpretation.
- [ ] Dry-run leaves no hook marker, download or archive. Compile-only runs
preparation and packaging with no token, tag, release or push.
- [ ] Changing a hook/input/license/dependency digest invalidates affected bundle
reuse while permitting unchanged Rust binaries to remain cached.
- [ ] Repeated packaging of identical inputs is byte-identical; stale staging
files never appear in a later archive; executable modes are correct.
- [ ] Mocked publication includes all bundle checksums, collision checks and
post-upload verification; one failed target causes no release creation.
- [ ] Existing cargo-binstall checks still pass and are reported separately from
portable-tree and native-runtime checks.
- [ ] Update upstream docs/schema/examples and implement a consumer migration
recipe using the actual downloader, not an FFmpeg-specific publisher fork.
Final consumer smoke test, once the implementation is available:
1. Configure the portable bundle and thin downloader adapter in this project.
2. Run `rust_realease . --package pptx-reporter --compile-only`.
3. Verify both portable archives and checksums, and run Linux extraction/probing
and report generation using the bundled FFprobe without relying on PATH.
4. On Windows, extract the ZIP and launch the GUI without Python, Typst or system
FFmpeg. Generate reports using its adjacent FFprobe. Record this as unverified
if no Windows validation machine is available.
5. Confirm no dependency binary, archive or generated staging file entered Git.
Remove the separate project archive packager once upstream owns its function.
Do not create an actual public release merely to test this task. This project's
Jenkins remains checks/coverage/badges only; release publication stays explicit.
Signing, installers, automatic updates and rewriting dependency downloaders in
Rust are outside this task.

View File

@ -1,4 +1,8 @@
# PPTX video reports
# Report options and Python reference
Report semantics apply to both implementations. Commands below use the Python
reference; for the desktop app and Rust CLI see [Reporter](rust-reporter.md).
Only the Python implementation needs the external Typst CLI for PDFs.
Extract videos and create Markdown and Ontime timing reports:
@ -33,8 +37,7 @@ presentation_videos/
Markdown and HTML links point to `../videos/`; JSON `extracted_file` paths are
relative to the report directory too. `--timings-only` reuses media in `videos/`
when available, otherwise probes temporary copies without creating that folder.
`--extract-only` creates no report folder. Existing files from the old flat
layout are not moved automatically.
`--extract-only` creates no report folder.
PDF uses the Typst CLI and retains `timings.typ`
for editing. HTML and Typst/PDF include colored summary cards and pills;
@ -53,7 +56,6 @@ Slide numbers and media names are plain text; durations and loop markers use pil
Trimmed videos show a discreet line under the media name with the amounts removed
from the start and end. Looping videos carry an amber **Looping** pill next to
their name and a dash instead of a finite duration.
The duration caveat stays in a small footnote.
Use `--report pdf,pdf-dense` to produce both layouts.
Timings require `ffprobe` (from FFmpeg); PDF additionally requires `typst` on
@ -90,7 +92,7 @@ there is no usable duration.
JSON retains file-level metadata under `videos`, with per-occurrence settings,
trim offsets, original/effective durations, status, and diagnostic notes under
`playbacks`. `total_duration_seconds` now totals effective occurrences;
`playbacks`. `total_duration_seconds` totals effective occurrences;
`total_media_duration_seconds` retains the original once-per-file total.
Implementation references:

71
docs/releases.md Normal file
View File

@ -0,0 +1,71 @@
# Cross builds and portable releases
Run these commands from the repository root. Cross needs Docker or Podman;
`Cross.toml` selects Windows GNU x64 and Linux GNU x64 images. Jenkins does not
run release builds or publish releases.
```sh
cross build --locked -p pptx-reporter --release --target x86_64-pc-windows-gnu
cross build --locked -p pptx-reporter --release --target x86_64-unknown-linux-gnu
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 packager reads `target/<target>/release/` and produces a Windows ZIP or Linux
`.tar.gz` in `dist/`, plus a SHA-256 checksum. Each includes GUI and CLI binaries,
FFprobe, licenses/provenance and quick-start instructions. Existing archives
are protected; use `--output DIR` for a new test build.
## FFprobe
`scripts/fetch_ffprobe.py` downloads BtbN FFmpeg 9.0 release-branch, non-shared
LGPL builds. It verifies GitHub's archive SHA-256, executable format and x86-64
architecture, then tests `ffprobe -version` on a matching host. Foreign binaries
are inspected without execution. Verified binaries/notices are cached in
ignored `downloads/ffprobe/`; no FFprobe binary is committed.
The default upstream `latest` tag moves. Pin repeatable builds with
`--ffprobe-release TAG --ffprobe-sha256 HASH`. Provenance records release/asset
IDs, download URL and digest. Cached files are checked on reuse, but online
metadata verification still requires GitHub access.
For offline packaging or another provider:
```sh
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
--ffprobe /path/to/ffprobe.exe --ffprobe-licenses /path/to/notices
```
Review upstream platform requirements and distribution notices for the selected
build. Test Windows launch, drag/drop, file dialogs, scaling, Unicode paths and
opening reports on a Windows machine; cross-compilation alone cannot verify them.
## Release automation
Root `Cargo.toml` → `workspace.package.version` is authoritative. The reporter
inherits it; its manifest contains cargo-binstall metadata. `rust-release.toml`
configures targets and the canonical Gitea URL for
[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease):
```sh
rust_realease . --package pptx-reporter --dry-run
rust_realease . --package pptx-reporter --compile-only
```
Publication needs a clean checkout and a matching explicitly created/pushed
version tag. The existing local `v0.1.0` marks the original trial, not subsequent
changes; do not move it implicitly. `rust_realease` currently packages Cargo
binaries only: use the portable packager for bundles containing FFprobe.
Upstream hook support is tracked separately.
## Application artwork
Artwork and fonts live in `crates/pptx-reporter/assets/`. Builds embed the PNG
window icon and the ICO Windows resource without image conversion tools.
To regenerate derivatives with ImageMagick from that directory:
```sh
magick rust-report.png -resize 256x256 -background none -gravity center \
-extent 256x256 rust-report-icon.png
magick rust-report-icon.png -define icon:auto-resize=256,128,64,48,32,24,16 rust-report.ico
```

View File

@ -1,76 +0,0 @@
# Rust reporter trial
Branch: `feature/rust-reporter`. Scope: PPTX video reporter only; the document
exporter stays in Python. Python remains the regression reference during the trial.
- [x] Read local instructions, coverage task, and `rust_realease` contract.
- [x] Resolve canonical badge owner/project/default branch: `Beffroi/beffroi-tools/main`.
- [x] Port ZIP discovery, presentation ordering, media extraction and metadata.
- [x] Port per-shape trims, looping/unsupported timing and effective durations.
- [x] Preserve HTML, Markdown, TXT, JSON, Typst, PDF, dense PDF and Ontime.
- [x] Embed Typst and a report font; locate bundled/system FFprobe.
- [x] Provide CLI parity and progress events shared with the GUI.
- [x] Add drag/drop, file picker, options, background jobs, cancellation, ETA,
result actions and remembered settings to the desktop app.
- [x] Prepare Windows GNU and Linux Cross builds, portable packaging and
`rust_realease` metadata; keep release creation outside Jenkins.
- [x] Add default-branch version/test/coverage badges and safe publication.
- [x] Test parity, errors, report rendering, GUI state, badge rendering,
coverage gating and publication with temporary fixtures.
- [x] Run format, lint, docs, tests, measured coverage and available cross builds.
- [x] Record unavailable Windows/Jenkins/live-publication checks explicitly.
- [x] Commit the completed trial on the feature branch.
The badge renderer is copied from `Dandaedre/agent-tasks` revision
`8923682b958de698c5ec41f4275bfc6f7e44a2f6`. CI may publish the three mutable badges
on `main`; it must never create a release, tag, or upload release binaries.
## Verification and remaining deployment checks
- Python: 57 tests, including badge rendering, failed/below-floor coverage,
publication permissions/symlink migration, and portable archive contents.
- Rust: 14 tests with all features; 10 with default features disabled.
The GUI tests feed egui input without a display and cover drop validation,
progress, error/completion state, and bounded activity history.
- Formatting, Clippy with warnings denied, and rustdoc with warnings denied pass.
- Measured Rust line coverage: **83.84%**, above the **75%** gate, with no
production-code exclusions. Cleanup leaves exactly three valid SVG badges.
- Real-media parity: report JSON and Ontime JSON match Python exactly for the
synthetic trim/loop/custom-timing fixture. Every report format is generated.
- Full and dense PDF pages were rendered and visually inspected. The Linux
desktop app was launched and its window inspected.
- Windows GNU and Linux GNU release executables cross-compile successfully
with Cross 0.2.5 and its main images (Rust 1.99.1). PE inspection
confirms the GUI subsystem and only Windows system DLL imports.
- `rust_realease` 0.1.6-rc.2 accepts metadata, both binaries, targets, and the
canonical Gitea destination. A publishing dry-run reports the intentionally
absent `v0.1.0` tag; it creates nothing.
- `rust_realease . --package pptx-reporter --compile-only --skip-tests` also
succeeded: both fresh Cross builds and both `.tgz` archives were verified.
Tests had already passed separately. These local archives contain the two
Cargo binaries only; FFprobe is added by the separate portable packager.
- The cross-built Linux release binary passes the same real-media parity check.
External checkpoints still required before distributing a Windows release:
- [ ] Run on a real Windows machine: drag/drop, file dialogs, scaling, Unicode
paths, opening reports, and a standalone target FFprobe beside the app.
- [x] Add release-time downloading of BtbN's target FFprobe with archive checksum,
executable architecture checks, upstream license and provenance. Keep
downloads and portable bundles ignored by Git.
- [ ] Review dependency notices before distribution.
- [ ] Configure/execute the actual Jenkins Multibranch job and confirm that its
`rust_no_docker` worker has the documented dependencies and asset mount.
- [ ] Confirm actual Jenkins archival, default-branch publication and all three
public badge responses after an authorized push/main build. Local tests
validate generated SVGs and publication into temporary directories only.
No production asset mount was modified and no push or release was made.
The subsequent local `v0.1.0` tag marks the original trial commit `2591252`;
release-time FFprobe fetching is a later follow-up change.
FFprobe follow-up validation: both target downloads passed checksum and
architecture checks; the Linux binary successfully probed real MPEG4 media.
Both portable archives were built with `--fetch-ffprobe`. Windows executable
imports were inspected; actual Windows execution remains unchecked.

View File

@ -1,12 +1,7 @@
# Rust PPTX reporter trial
# PPTX reporter
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
Create video timing reports from a PowerPoint presentation using the desktop
app or CLI. Python and PowerPoint are not required for the Rust application.
```sh
cargo run --locked --bin pptx-reporter-gui
@ -14,208 +9,35 @@ cargo run --locked --bin pptx-reporter -- presentation.pptx --timings-only --rep
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.
Drop one PPTX into the window or choose a file. Check the save location, choose
extraction/report mode, select formats, then use the purple action button.
Reading & printing selects HTML, PDF and compact PDF; Defaults selects Markdown
and Ontime. Advanced contains video replacement and FFprobe location controls.
The app remembers options and the last eight presentations. Completed files
can be opened directly or their paths copied.
`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.
Progress estimates apply to the current counted phase. Cancel interrupts
FFprobe and stops between steps; an active PDF compilation finishes first.
Activity & diagnostics retains warnings and details.
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).
## Files and dependencies
## Development and checks
Output defaults to `<presentation>_videos/`, with `videos/` and `reports/`
subfolders. Reports are regenerated; extracted videos are reused unless
`--overwrite` is selected. Empty presentations create no output.
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.
HTML, Markdown, plain text, JSON, Typst, PDF, compact PDF and Ontime are supported.
Durations account for per-shape trims. Loops and unsupported timing stay visible
in reports but are omitted from Ontime and playback totals. Extracted media
remains unchanged. See [report options and semantics](pptx-videos.md).
The app uses `assets/rust-report.png` as its icon. Its square, transparent PNG
derivative is embedded in the desktop window; the multi-resolution ICO is also
embedded into Windows executables by `build.rs` using `winresource`. Cross's
Windows GNU image supplies the resource compiler. Normal builds need no image
conversion tools. To regenerate the committed icon derivatives after changing
the source artwork, use ImageMagick:
PDF compilation and fonts are embedded; no Typst installation or package
downloads are needed. FFprobe is discovered beside the app, in its `bin/`
subfolder, or on PATH. Override with `--ffprobe PATH` or Advanced in the GUI.
```sh
magick assets/rust-report.png -resize 256x256 -background none -gravity center \
-extent 256x256 assets/rust-report-icon.png
magick assets/rust-report-icon.png \
-define icon:auto-resize=256,128,64,48,32,24,16 assets/rust-report.ico
```
On Windows, extract the whole portable ZIP and launch `pptx-reporter-gui.exe`.
`pptx-reporter.exe` provides the CLI and opens the GUI when given no arguments.
Linux desktop builds need windowing/OpenGL libraries at runtime.
```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.
See [development](development.md) for source checks and [releases](releases.md)
for Cross builds, packaging and dependency provenance.

View File

@ -10,7 +10,7 @@ locked = true
format = "tgz"
# rust_realease packages Cargo binaries only. Release automation can additionally
# call: python3 scripts/package-portable.py --target TARGET --fetch-ffprobe
# after Cross builds populate target/TARGET/release (see docs/rust-reporter.md).
# after Cross builds populate target/TARGET/release (see docs/releases.md).
[[repository.fallbacks]]
origin = "https://git.dandaedre.com/Beffroi/beffroi-tools"

View File

@ -73,7 +73,7 @@ def finalize():
render("test", "passing" if passed.is_file() else "failing")
if not ready.is_file():
render("coverage", "-")
version = tomllib.loads((ROOT / "Cargo.toml").read_text())["package"]["version"]
version = tomllib.loads((ROOT / "Cargo.toml").read_text())["workspace"]["package"]["version"]
render("version", version)
summary = Path("coverage/measurement.txt")
lines = summary.read_text().splitlines() if summary.is_file() else []

View File

@ -57,7 +57,7 @@ def main():
parser.error(f"Wrong target binary format: {path}")
if not args.ffprobe_licenses.is_dir() or not any(args.ffprobe_licenses.iterdir()):
parser.error("Supply the FFprobe distribution's licence/provenance directory.")
version = tomllib.loads((ROOT / "Cargo.toml").read_text())["package"]["version"]
version = tomllib.loads((ROOT / "Cargo.toml").read_text())["workspace"]["package"]["version"]
stem = f"pptx-reporter-portable-{args.target}-v{version}"
args.output.mkdir(parents=True, exist_ok=True)
destination = args.output / (stem + (".zip" if windows else ".tar.gz"))
@ -72,7 +72,7 @@ def main():
licenses = folder / "LICENSES"
licenses.mkdir()
shutil.copy2(ROOT / "LICENSE", licenses / "reporter-MIT.txt")
shutil.copy2(ROOT / "assets/fonts/LICENSE", licenses / "DejaVu.txt")
shutil.copy2(ROOT / "crates/pptx-reporter/assets/fonts/LICENSE", licenses / "DejaVu.txt")
shutil.copytree(args.ffprobe_licenses, licenses / "ffmpeg")
shutil.copy2(ROOT / "docs/windows-quickstart.txt", folder / "README.txt")
if windows:

View File

@ -7,6 +7,7 @@ from pathlib import Path
import stat
import subprocess
import tempfile
import tomllib
import unittest
from unittest.mock import patch
from xml.etree import ElementTree as ET
@ -85,6 +86,10 @@ class BadgeTests(unittest.TestCase):
with contextlib.redirect_stdout(io.StringIO()):
ci.finalize()
self.assertEqual(Path("coverage/coverage.svg").read_bytes(), measured)
public = self.root / "public"
public.mkdir(exist_ok=True)
self.assertEqual(self.publish(public, "version", "test", "coverage").returncode, 0)
self.assertEqual((public / "Beffroi/beffroi-tools/main/coverage.svg").read_bytes(), measured)
self.assertFalse(Path("coverage/.coverage-ready-42").exists())
self.assertIn("failing", Path("coverage/test.svg").read_text())
@ -145,3 +150,19 @@ class BadgeTests(unittest.TestCase):
self.assertEqual(text.count(f"https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/{kind}.svg"), 1)
self.assertIn("artifacts: 'coverage/version.svg,coverage/test.svg,coverage/coverage.svg'",
(ROOT / "Jenkinsfile").read_text())
def test_workspace_version_and_fresh_build_lifecycle(self):
with patch.dict(os.environ, {"BUILD_NUMBER": "44"}):
Path("coverage/stale.svg").write_text("old")
Path("coverage/.tests-passed-43").touch()
with patch("sys.argv", ["ci.py", "init"]):
ci.main()
self.assertEqual(list(Path("coverage").iterdir()), [])
with contextlib.redirect_stdout(io.StringIO()):
ci.finalize()
version = tomllib.loads((ROOT / "Cargo.toml").read_text())["workspace"]["package"]["version"]
self.assertIn(version, Path("coverage/version.svg").read_text())
self.assertIn("failing", Path("coverage/test.svg").read_text())
self.assertIn("-%", Path("coverage/coverage.svg").read_text())
self.assertEqual({p.name for p in Path("coverage").iterdir()},
{"version.svg", "test.svg", "coverage.svg"})

View File

@ -27,11 +27,11 @@ class PortableTests(unittest.TestCase):
licenses = root / "ffmpeg-licenses"
licenses.mkdir()
(licenses / "LICENSE").write_text("fixture notice")
for file in ("LICENSE", "assets/fonts/LICENSE", "docs/windows-quickstart.txt"):
for file in ("LICENSE", "crates/pptx-reporter/assets/fonts/LICENSE", "docs/windows-quickstart.txt"):
path = root / file
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("fixture")
(root / "Cargo.toml").write_text('[package]\nversion = "0.1.0"\n')
(root / "Cargo.toml").write_text('[workspace.package]\nversion = "0.1.0"\n')
output = root / "dist"
args = ["package-portable.py", "--target", target, "--ffprobe", str(probe),
"--ffprobe-licenses", str(licenses), "--output", str(output)]