workflow: add unified reporting entry point
This commit is contained in:
parent
9d4e3f9f6e
commit
2356e2c7a5
|
|
@ -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
174
README.md
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
2
reporter
2
reporter
|
|
@ -1 +1 @@
|
|||
Subproject commit 7a7ba72524a30ece719f7ec4ab0209701d40ff92
|
||||
Subproject commit 79179b2f6844bc76ee062d18a6b4cc4c9a736121
|
||||
2
reports
2
reports
|
|
@ -1 +1 @@
|
|||
Subproject commit 11cd0f615bddb13bc5eb34287fc431509d981f5f
|
||||
Subproject commit 5cf1945f56b30e2bcc4d6221ff07a2b1bfe616c0
|
||||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue