reportist/docs/plugins.md

65 lines
3.2 KiB
Markdown

# Writing a Reportist plugin
A plugin is a self-contained way to turn one source format into a document.
It owns interpretation and layout, and can use the shared graphical elements.
The existing `plugins/report/` and `plugins/diagnostics/` are examples, not
schemas that every new plugin must imitate.
## Minimum contract
1. Give the plugin a stable kind name and document the input files it accepts.
Place its Typst source under `plugins/<kind>/`; keep normalization and
document composition in that plugin. Add a README with one standalone
render command and any required options.
2. Add a small shell entry point that stages the source, plugin Typst files,
themes, visual assets, and any plugin rules into a temporary directory,
runs Typst, and moves a completed PDF into place. Use
`tools/render-common.sh` for common options, path checks, `--force`, and
cleanup. Do not depend on a sibling repository or the macro checkout.
3. Route the kind through `build.sh render` and `render-all`. State its source
extensions in the batch filter; preserve relative paths. Extend `validate`
only if the plugin needs a separate validation command. If it produces a
non-PDF artifact, add an explicit command and document its contract.
4. Add a valid fixture, invalid-input and overwrite checks, and a standalone
render test in `tests/` or `plugins/<kind>/tests/`. Have `tests/test.sh`
run them. Update the macro integration checks only when macro publication
should include the new source set.
A typical plugin layout is:
```text
plugins/<kind>/
README.md
render.sh
renderer/render.typ
renderer/model.typ
renderer/normalize.typ # only if the input needs interpretation
runtime/ # optional rules or other plugin data
tests/ # fixtures and focused tests
```
## Boundaries to preserve
- `visual/elements.typ` and `visual/themes.yaml` are the shared visual
vocabulary. Add a reusable primitive there when several plugins need it;
keep page structure and plugin-specific presentation in the plugin.
- Read YAML/JSON, normalize values, validate domain facts, choose themes, and
assemble pages in Typst. Use shell or Python for directory traversal, safe
paths, hashes, temporary files, atomic replacement, and archives.
- Do not transform a new plugin's input into the authored report schema merely
to reuse `plugins/report/model.typ`. Share graphic elements instead.
- Keep input, intermediate evidence, and generated PDF distinct. The
diagnostic analyzer produces normalized evidence JSON, while the diagnostic
PDF renderer reads the raw capture. New plugins may have no intermediate.
- Reportist must render one input from its own checkout. The Reports repository
contains source content; the macro repository alone assembles publications.
## Review before merging
Run the plugin tests and `tests/test.sh` from Reportist. For changes to an
existing plugin, compare the approved fixture PDFs; the macro's current
regression suite checks 17 legacy outputs. Document intentional output changes
and update the oracle only after review. Run the macro `./beffroi.sh test` when
its stored sources or shared visual elements change. Keep both plugin behavior
and command examples in sync with `docs/build-cli.md`.