Organize Rust workspace and finalize CI and documentation
This commit is contained in:
parent
ac5d586099
commit
534cce41cd
|
|
@ -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"
|
||||
|
|
|
|||
18
AGENTS.md
18
AGENTS.md
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
47
Cargo.toml
47
Cargo.toml
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
'''
|
||||
|
|
|
|||
32
README.md
32
README.md
|
|
@ -4,33 +4,21 @@
|
|||

|
||||

|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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 }"
|
||||
|
Before Width: | Height: | Size: 76 KiB After Width: | Height: | Size: 76 KiB |
|
Before Width: | Height: | Size: 364 KiB After Width: | Height: | Size: 364 KiB |
|
Before Width: | Height: | Size: 1.3 MiB After Width: | Height: | Size: 1.3 MiB |
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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 []
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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"})
|
||||
|
|
|
|||
|
|
@ -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)]
|
||||
|
|
|
|||
Loading…
Reference in New Issue