diff --git a/.cargo/config.toml b/.cargo/config.toml index 2063d5f..1d2bcd5 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -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" diff --git a/AGENTS.md b/AGENTS.md index c75fc86..f6e3330 100644 --- a/AGENTS.md +++ b/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//`: 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. diff --git a/Cargo.toml b/Cargo.toml index 9057948..3e3fa31 100644 --- a/Cargo.toml +++ b/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 diff --git a/Jenkinsfile b/Jenkinsfile index 6e8879f..64c4156 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -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 ''' diff --git a/README.md b/README.md index 1312f5a..77419b9 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/coverage.toml b/coverage.toml index 4660418..1debbf2 100644 --- a/coverage.toml +++ b/coverage.toml @@ -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" diff --git a/crates/pptx-reporter/Cargo.toml b/crates/pptx-reporter/Cargo.toml new file mode 100644 index 0000000..a00f00b --- /dev/null +++ b/crates/pptx-reporter/Cargo.toml @@ -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 }" diff --git a/assets/fonts/DejaVuSans-Bold.ttf b/crates/pptx-reporter/assets/fonts/DejaVuSans-Bold.ttf similarity index 100% rename from assets/fonts/DejaVuSans-Bold.ttf rename to crates/pptx-reporter/assets/fonts/DejaVuSans-Bold.ttf diff --git a/assets/fonts/DejaVuSans.ttf b/crates/pptx-reporter/assets/fonts/DejaVuSans.ttf similarity index 100% rename from assets/fonts/DejaVuSans.ttf rename to crates/pptx-reporter/assets/fonts/DejaVuSans.ttf diff --git a/assets/fonts/LICENSE b/crates/pptx-reporter/assets/fonts/LICENSE similarity index 100% rename from assets/fonts/LICENSE rename to crates/pptx-reporter/assets/fonts/LICENSE diff --git a/assets/report.css b/crates/pptx-reporter/assets/report.css similarity index 100% rename from assets/report.css rename to crates/pptx-reporter/assets/report.css diff --git a/assets/rust-report-icon.png b/crates/pptx-reporter/assets/rust-report-icon.png similarity index 100% rename from assets/rust-report-icon.png rename to crates/pptx-reporter/assets/rust-report-icon.png diff --git a/assets/rust-report.ico b/crates/pptx-reporter/assets/rust-report.ico similarity index 100% rename from assets/rust-report.ico rename to crates/pptx-reporter/assets/rust-report.ico diff --git a/assets/rust-report.png b/crates/pptx-reporter/assets/rust-report.png similarity index 100% rename from assets/rust-report.png rename to crates/pptx-reporter/assets/rust-report.png diff --git a/build.rs b/crates/pptx-reporter/build.rs similarity index 100% rename from build.rs rename to crates/pptx-reporter/build.rs diff --git a/src/archive.rs b/crates/pptx-reporter/src/archive.rs similarity index 100% rename from src/archive.rs rename to crates/pptx-reporter/src/archive.rs diff --git a/src/bin/gui.rs b/crates/pptx-reporter/src/bin/gui.rs similarity index 100% rename from src/bin/gui.rs rename to crates/pptx-reporter/src/bin/gui.rs diff --git a/src/engine.rs b/crates/pptx-reporter/src/engine.rs similarity index 100% rename from src/engine.rs rename to crates/pptx-reporter/src/engine.rs diff --git a/src/gui.rs b/crates/pptx-reporter/src/gui.rs similarity index 100% rename from src/gui.rs rename to crates/pptx-reporter/src/gui.rs diff --git a/src/lib.rs b/crates/pptx-reporter/src/lib.rs similarity index 100% rename from src/lib.rs rename to crates/pptx-reporter/src/lib.rs diff --git a/src/main.rs b/crates/pptx-reporter/src/main.rs similarity index 100% rename from src/main.rs rename to crates/pptx-reporter/src/main.rs diff --git a/src/model.rs b/crates/pptx-reporter/src/model.rs similarity index 100% rename from src/model.rs rename to crates/pptx-reporter/src/model.rs diff --git a/src/pdf.rs b/crates/pptx-reporter/src/pdf.rs similarity index 100% rename from src/pdf.rs rename to crates/pptx-reporter/src/pdf.rs diff --git a/src/playback.rs b/crates/pptx-reporter/src/playback.rs similarity index 100% rename from src/playback.rs rename to crates/pptx-reporter/src/playback.rs diff --git a/src/reports.rs b/crates/pptx-reporter/src/reports.rs similarity index 100% rename from src/reports.rs rename to crates/pptx-reporter/src/reports.rs diff --git a/tests/reporter.rs b/crates/pptx-reporter/tests/reporter.rs similarity index 100% rename from tests/reporter.rs rename to crates/pptx-reporter/tests/reporter.rs diff --git a/docs/ci.md b/docs/ci.md new file mode 100644 index 0000000..60d23e7 --- /dev/null +++ b/docs/ci.md @@ -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. diff --git a/docs/development.md b/docs/development.md index 4c61d49..b6b240a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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//` | 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). diff --git a/docs/fix-rust-realease.task.md b/docs/fix-rust-realease.task.md deleted file mode 100644 index 0d491b9..0000000 --- a/docs/fix-rust-realease.task.md +++ /dev/null @@ -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//release/`. -- 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--v/ - pptx-reporter[.exe] - pptx-reporter-gui[.exe] - ffprobe[.exe] - README.txt - LICENSES/ - reporter-MIT.txt - DejaVu.txt - ffmpeg/ - - 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": "" - }, - { - "source": "notices/provenance.json", - "destination": "LICENSES/ffmpeg/provenance.json", - "kind": "file", - "sha256": "" - }, - { - "source": "notices/LICENSE.txt", - "destination": "LICENSES/ffmpeg/LICENSE.txt", - "kind": "file", - "sha256": "" - } - ] -} -``` - -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. diff --git a/docs/pptx-videos.md b/docs/pptx-videos.md index 3d7f4f8..6c4aae5 100644 --- a/docs/pptx-videos.md +++ b/docs/pptx-videos.md @@ -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: diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 0000000..a7d629b --- /dev/null +++ b/docs/releases.md @@ -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//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 +``` diff --git a/docs/rust-reporter-tasks.md b/docs/rust-reporter-tasks.md deleted file mode 100644 index 1553c4b..0000000 --- a/docs/rust-reporter-tasks.md +++ /dev/null @@ -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. diff --git a/docs/rust-reporter.md b/docs/rust-reporter.md index 3f1a444..536597b 100644 --- a/docs/rust-reporter.md +++ b/docs/rust-reporter.md @@ -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 `_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 `_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//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///`. 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. diff --git a/rust-release.toml b/rust-release.toml index 91999a0..32a029f 100644 --- a/rust-release.toml +++ b/rust-release.toml @@ -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" diff --git a/scripts/ci.py b/scripts/ci.py index 4822801..5f47ce9 100644 --- a/scripts/ci.py +++ b/scripts/ci.py @@ -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 [] diff --git a/scripts/package-portable.py b/scripts/package-portable.py index dafa555..281abbb 100644 --- a/scripts/package-portable.py +++ b/scripts/package-portable.py @@ -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: diff --git a/tests/test_ci_badges.py b/tests/test_ci_badges.py index 15e5480..40cb83a 100644 --- a/tests/test_ci_badges.py +++ b/tests/test_ci_badges.py @@ -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"}) diff --git a/tests/test_portable.py b/tests/test_portable.py index 2b72dae..927a0c6 100644 --- a/tests/test_portable.py +++ b/tests/test_portable.py @@ -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)]