reportist/docs/plugins.md

3.2 KiB

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:

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.