Document Reportist plugin contract and agent guidance

This commit is contained in:
Dandaedre 2026-09-17 00:10:54 +02:00
parent b268af7cb7
commit 6f29f59d54
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 93 additions and 34 deletions

13
AGENTS.md Normal file
View File

@ -0,0 +1,13 @@
# Reportist plugin instructions
For a new plugin, read `docs/plugins.md` and `docs/build-cli.md` first.
- Keep each plugin's source interpretation and Typst document model inside
`plugins/<kind>/`. There is no shared report-shaped IR.
- Share visual primitives through `visual/`; do not copy styles into plugins.
- Make `build.sh` the public route and keep the plugin usable from a standalone
Reportist checkout. Use `tools/render-common.sh` for shell output rules.
- Put data checks and layout in Typst; leave file traversal, staging, hashes,
overwrite protection, and publication to shell/Python.
- Add focused plugin tests and preserve approved PDF output. If macro sources
use the plugin, also run the macro integration/parity suite.

View File

@ -1,18 +1,18 @@
# Reportist
Reportist renders authored YAML/JSON reports and raw WinDiagnostics captures.
The report and diagnostic plugins own their document structure independently;
both use `visual/elements.typ` and `visual/themes.yaml`.
`build.sh` is the public CLI and works without the Beffroi macro checkout:
Reportist is the standalone Typst engine for authored reports and raw
WinDiagnostics captures. Each plugin owns its input interpretation and document
layout. Plugins share graphical elements and themes in `visual/`.
```bash
./build.sh render report examples/example-report.yaml --output report.pdf
./build.sh render diagnostic plugins/diagnostics/tests/fixtures/legacy/windiagnostics-v1.json --output diagnostic.pdf
./build.sh render-all report /path/to/reports --output-dir /path/to/pdfs
./build.sh render-all diagnostic /path/to/captures --output-dir /path/to/pdfs
./tests/test.sh
```
It also exposes `analyze`, `analyze-all`, `validate`, `validate-all`, and
`export-json-all`. See [the CLI contract](docs/build-cli.md) for arguments and
output behavior. `tests/test.sh` runs both plugin test suites.
The public CLI also renders source directories, analyzes diagnostic evidence,
validates inputs, and exports authored YAML as JSON. See the
[CLI contract](docs/build-cli.md) for commands and output behavior, the
[plugin guide](docs/plugins.md) to add a renderer, and the
[authored report contract](docs/report-contract.md) for report input. The
`AGENTS.md` file is a short implementation manifest for coding agents.

View File

@ -1,15 +0,0 @@
# Report plugin development
`plugins/report/render.typ` and `plugins/report/model.typ` own authored report
structure. `render.sh` stages these files with the shared `visual/elements.typ`,
`visual/themes.yaml`, and logo. The diagnostic plugin imports the same visual
module but keeps its own Typst document logic.
Run `tests/test.sh` for both plugin suites. In the integration repository,
`../beffroi.sh test` rebuilds seven authored reports and ten diagnostics and
compares them with the original Typst PDFs. When the local reference exists,
the comparison includes rasterized pages.
The old Reportist v1 schema, IR adapter, and their test oracle were retired.
The active report validator compiles with the report plugin so its checks stay
aligned with rendering. `build.sh` is the public CLI for both plugins.

View File

@ -1,7 +0,0 @@
# Renderer ownership
The report plugin owns authored report structure in `plugins/report`.
The diagnostic plugin owns WinDiagnostics interpretation and document structure
in `plugins/diagnostics/renderer`. Shared graphic primitives and theme
palettes live in `visual`. The previous report-shaped diagnostic
adapter and Reportist IR path were retired.

64
docs/plugins.md Normal file
View File

@ -0,0 +1,64 @@
# 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`.

View File

@ -4,7 +4,7 @@ The report plugin accepts YAML or JSON dictionaries. `metadata.Date` and
`metadata.Author` are required. The document model supports report-specific
fields such as `diagnostics` as well as ordinary sections, findings, actions,
and appendices. Named themes are `default`, `cic`, and `eridani`; a custom theme
dictionary can be provided. The renderer is `reporter/plugins/report`.
dictionary can be provided. The renderer is `plugins/report/`.
The diagnostic plugin has a separate raw WinDiagnostics input and its own Typst
document model. Both plugins import `reporter/visual/elements.typ` for graphical

View File

@ -6,7 +6,7 @@ builds its PDF with `renderer/render.typ`, `renderer/normalize.typ`, and
local Reportist visual module; it does not convert the capture into a report model.
```bash
./render.sh /path/to/capture.json --output diagnostic.pdf --author 'Reviewer' --theme cic
../../build.sh render diagnostic /path/to/capture.json --output diagnostic.pdf --author 'Reviewer' --theme cic
```
Themes are `default`, `cic`, and `eridani`. The integration command
@ -14,3 +14,7 @@ Themes are `default`, `cic`, and `eridani`. The integration command
`analyse.sh` remains available when normalized diagnostic JSON v1 and evidence
pointers are needed. Its output is independent of the source-faithful PDF path.
The public entry point is `../../build.sh`. The plugin also supplies evidence
validation and analysis commands through that CLI. See
[the plugin guide](../../docs/plugins.md) for ownership rules and tests.