2.4 KiB
Project vision
Beffroi Reporting turns reviewed source material into reproducible PDF reports. An authored report and a machine capture are different kinds of source; each gets a renderer that understands its own meaning and layout. They can share a visual language without sharing a forced document schema.
The three repositories
| Repository | Owns | Does not own |
|---|---|---|
| Beffroi Reporting (macro) | Editing workspace, pinned components, integration checks, publication staging, encrypted archives, deployment CI | Report layouts or diagnostic rules |
| Beffroi Reports | Authored YAML/JSON and raw diagnostic captures, with editorial provenance and syntax checks | Executable rendering or analysis code |
Reportist (reporter/ here) |
Standalone renderers, diagnostic analysis, validation, shared graphical elements, themes, plugin tests, and build.sh |
The production source collection or publication destination |
A Reportist plugin owns its input format, interpretation, validation, and Typst document model. The report plugin and diagnostic plugin are peers. A future plugin may produce a document with a different structure; it should use shared visual elements where useful, but should not be translated into the report plugin's data shape simply to render.
The common surface is graphical: palettes, badges, pills, headings, panels,
callouts, progress bars, and similar reusable elements in reporter/visual/.
Plugin-specific composition remains in reporter/plugins/<name>/.
Working rules
- Source content stays reviewable in text files. Generated PDFs and encrypted archives are build artifacts.
- Typst handles structured data, interpretation, and page composition. Shell or Python handles directory traversal, input staging, hashes, atomic output, encryption, Git, and CI deployment.
- A plugin must work from a standalone Reportist checkout. The macro checkout may call it, but must not be required by it.
- Changes to existing renderers must preserve approved output. The current regression baseline covers seven authored reports and ten diagnostics.
- The macro Jenkins pipeline is the publishing authority. Reportist's CI tests its own code; Reports CI checks source syntax without rendering.
See architecture for the component boundaries and operations for the editing and publishing workflow. New renderers follow the Reportist plugin guide.