workflow: add unified reporting entry point

This commit is contained in:
Dandaedre 2026-09-16 02:03:19 +02:00
parent 9d4e3f9f6e
commit 2356e2c7a5
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 118 additions and 135 deletions

6
Jenkinsfile vendored
View File

@ -35,7 +35,7 @@ pipeline {
stage('Test Components and Integration') {
steps {
sh 'scripts/check-components.sh'
sh './beffroi.sh test'
}
}
@ -44,7 +44,7 @@ pipeline {
sh '''
set -eu
rm -rf "${CI_REPORT_DIR}" "${CI_ARTIFACT_DIR}"
scripts/build-publication.sh "${CI_REPORT_DIR}"
./beffroi.sh all "${CI_REPORT_DIR}"
'''
}
}
@ -57,7 +57,7 @@ pipeline {
sh '''
set +x
set -eu
scripts/package-reports.sh "${CI_REPORT_DIR}" "${CI_ARTIFACT_DIR}"
./beffroi.sh package "${CI_REPORT_DIR}" "${CI_ARTIFACT_DIR}"
'''
archiveArtifacts artifacts: '.ci-artifacts/*.zip.enc', fingerprint: true
}

174
README.md
View File

@ -1,133 +1,55 @@
# Beffroi Reporting
Beffroi Reporting is a reproducible workspace for turning Windows diagnostic
captures into structured findings and PDF reports. It pins compatible revisions
of three independent tools:
Beffroi Reporting turns structured reports and Windows diagnostic captures into
PDFs. The root `beffroi.sh` command is the main entry point.
| Directory | Component | Responsibility |
| --- | --- | --- |
| `diagnostics/` | Win Diagnostics | Normalizes captures and produces traceable diagnostic findings |
| `reports/` | Beffroi Reports | Creates immutable report drafts with evidence and provenance |
| `reporter/` | Reportist | Validates YAML or JSON report definitions and renders PDFs with Typst |
## Generate one personal report
Write a Reportist YAML or JSON file, then run:
```bash
./beffroi.sh report my-report.yaml my-report.pdf
```
See [`reporter/examples`](reporter/examples) for complete inputs.
## Generate one diagnostic report
```bash
./beffroi.sh diagnostic \
capture.json /path/to/evidence /path/to/new-output \
2026-09-15T12:00:00Z 'Diagnostic review' 'Reviewer Name' 2026-09-15
```
The output contains the normalized diagnostic, evidence-backed draft generation,
and rendered PDF.
## Generate every stored PDF
Add report YAML files under
[`reports/reports`](reports/reports)
or diagnostic JSON captures under
[`reports/diagnostics`](reports/diagnostics),
commit them with the reports submodule update, and run:
```bash
./beffroi.sh all build/publication
```
Jenkins runs the same build and publishes encrypted report archives from `main`.
## Commands
```text
Windows capture
↓
diagnostic.json
↓
reviewable report draft
↓
report.pdf
./beffroi.sh report INPUT OUTPUT.pdf
./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT OUTPUT_DIR REFERENCE_TIME TITLE AUTHOR DATE
./beffroi.sh all NEW_OUTPUT_DIR
./beffroi.sh package BUILD_DIR ARTIFACT_DIR
./beffroi.sh test
./beffroi.sh bootstrap
./beffroi.sh doctor
```
Each component can be used separately. This repository supplies the pinned
versions and high-level commands for the complete workflow.
## Requirements
The runtime uses Bash, Git, and Typst 0.15 or newer.
Selected report fonts must also be installed; the examples use DejaVu Sans and
DejaVu Sans Mono.
## Installation
Clone the workspace with its pinned submodules and run bootstrap:
```bash
git clone --recursive <repository-url>
cd beffroi-reporting
./bootstrap.sh
```
Bootstrap checks runtime dependencies, initializes the recorded submodule
revisions, and builds the publication helper. It does not install system
packages. For an existing checkout, the same command initializes any missing
submodules. Use `./bootstrap.sh --check` to verify dependencies and pins without
changing the checkout.
## Create a report
Run the complete workflow with an explicit capture, evidence root, and new work
directory:
```bash
scripts/workflow.sh all \
/path/to/evidence/capture.json \
/path/to/evidence \
/path/to/new-run \
2026-09-15T12:00:00Z \
'Diagnostic review' \
'Reviewer Name' \
2026-09-15
```
The work directory must not already exist. A successful run creates:
```text
new-run/
├── diagnostic.json
├── generation/
│ ├── diagnostic.json
│ ├── evidence/
│ ├── generation.json
│ └── report.draft.json
└── report.pdf
```
The generation directory is immutable and records source hashes, tool versions,
options, and evidence. Existing destinations are never overwritten.
Use the individual stages when a report needs review or editing between steps:
```bash
scripts/workflow.sh analyse CAPTURE EVIDENCE_ROOT OUTPUT REFERENCE_TIME
scripts/workflow.sh draft DIAGNOSTIC EVIDENCE_ROOT OUTPUT_DIR TITLE AUTHOR DATE
scripts/workflow.sh render REPORT OUTPUT
```
Process every JSON capture in a directory tree through all stages with:
```bash
scripts/workflow-all.sh CAPTURE_DIR EVIDENCE_ROOT OUTPUT_ROOT REFERENCE_TIME TITLE AUTHOR DATE
```
This creates parallel `diagnostics`, `generations`, and `pdfs` trees beneath a
new output root.
## Build publication archives
Build the preserved authored reports and diagnostic reports with:
```bash
scripts/build-publication.sh /path/to/new-publication-directory
```
Create password-encrypted publication artifacts with:
```bash
REPORT_ZIP_PASSWORD='...' scripts/package-reports.sh \
/path/to/publication-directory /path/to/artifacts
```
The result contains `Reports.zip.enc` and `Diagnostics.zip.enc`, encrypted with
AES-256-CBC and PBKDF2. Jenkins archives both files and publishes main-branch
builds to `/mnt/books/Reports` using the
`typst-reporter-publish-password` credential.
## Reproducibility
Git submodules pin exact component commits instead of following branch heads.
`git submodule status` shows the selected revisions. Record the root commit,
Typst version, and installed font files when reproducing a historical report.
PDF bytes can vary across Typst and font versions even when content and layout
remain equivalent.
## Contributing
See the [contributor guide](docs/development.md).
## License
Root-level orchestration software is licensed under the MIT License. Diagnostic
evidence, report content, and branding may have separate terms; see
[LICENSE.md](LICENSE.md).
The command reports missing tools for the requested operation. See
[`docs/development.md`](docs/development.md) for repository structure, testing,
publication details, and component development.

61
beffroi.sh Executable file
View File

@ -0,0 +1,61 @@
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
usage() {
cat <<'EOF'
Usage:
./beffroi.sh report INPUT OUTPUT.pdf
./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT OUTPUT_DIR REFERENCE_TIME TITLE AUTHOR DATE
./beffroi.sh all NEW_OUTPUT_DIR
./beffroi.sh package BUILD_DIR ARTIFACT_DIR
./beffroi.sh test
./beffroi.sh bootstrap
./beffroi.sh doctor
EOF
exit "${1:-0}"
}
require() {
local missing=() command
for command in "$@"; do command -v "$command" >/dev/null 2>&1 || missing+=("$command"); done
((${#missing[@]} == 0)) || { echo "Missing tools: ${missing[*]}" >&2; exit 1; }
}
command_name=${1:-help}; shift || true
case "$command_name" in
report)
[[ $# -eq 2 ]]||usage 2; require typst
reporter/tools/render.sh "$1" --output "$2"
;;
diagnostic)
[[ $# -eq 7 ]]||usage 2; require git typst
scripts/workflow.sh all "$@"
;;
all)
[[ $# -eq 1 ]]||usage 2; require git typst
scripts/build-publication.sh "$1"
;;
package)
[[ $# -eq 2 ]]||usage 2; require zip unzip openssl
scripts/package-reports.sh "$1" "$2"
;;
test)
[[ $# -eq 0 ]]||usage 2; require git typst uv
scripts/check-components.sh
;;
bootstrap)
[[ $# -eq 0 ]]||usage 2; require git typst
./bootstrap.sh
;;
doctor)
[[ $# -eq 0 ]]||usage 2
require git typst
echo "Core tools are available."
for optional in uv zip unzip openssl; do
if command -v "$optional" >/dev/null 2>&1; then "$optional" --version 2>/dev/null | head -n 1 || true; else echo "Optional tool missing: $optional"; fi
done
;;
help|-h|--help) usage 0;;
*) usage 2;;
esac

@ -1 +1 @@
Subproject commit 5770b61460ed69a095331916d6b5febcfc465182
Subproject commit bf331f6bdb34ee0056816dd12527ccb0f7b3a30b

@ -1 +1 @@
Subproject commit 7a7ba72524a30ece719f7ec4ab0209701d40ff92
Subproject commit 79179b2f6844bc76ee062d18a6b4cc4c9a736121

@ -1 +1 @@
Subproject commit 11cd0f615bddb13bc5eb34287fc431509d981f5f
Subproject commit 5cf1945f56b30e2bcc4d6221ff07a2b1bfe616c0

View File

@ -5,11 +5,11 @@ output_root=${1:-}
[[ -n "$output_root" && $# -eq 1 ]]||{ echo "Usage: $0 NEW_OUTPUT_ROOT" >&2; exit 2; }
[[ ! -e "$output_root" ]]||{ echo "$output_root: output root already exists" >&2; exit 1; }
mkdir -p "$output_root/reports" "$output_root/diagnostics"
reports/tools/convert-legacy-reports.sh reports/archive/typst_reporter/reports "$output_root/reports/sources"
reports/tools/convert-legacy-reports.sh reports/reports "$output_root/reports/sources"
reporter/tools/validate-all.sh "$output_root/reports/sources"
reporter/tools/render-all.sh "$output_root/reports/sources" --output-dir "$output_root/reports/pdfs"
scripts/workflow-all.sh reports/archive/typst_reporter/diagnostics \
reports/archive/typst_reporter/diagnostics "$output_root/diagnostic-work" \
scripts/workflow-all.sh reports/diagnostics \
reports/diagnostics "$output_root/diagnostic-work" \
2026-09-15T12:15:00Z 'Diagnostic report' "${DIAGNOSTICS_AUTHOR:-Beffroi}" 2026-09-15
cp -R "$output_root/diagnostic-work/pdfs/." "$output_root/diagnostics/"
echo "Built publishable reports under $output_root"