From 6f29f59d54773e7f305ebfe6e249ad5c68d8efcc Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 17 Sep 2026 00:10:54 +0200 Subject: [PATCH] Document Reportist plugin contract and agent guidance --- AGENTS.md | 13 +++++++ README.md | 20 +++++------ docs/development.md | 15 -------- docs/migration-inventory.md | 7 ---- docs/plugins.md | 64 +++++++++++++++++++++++++++++++++++ docs/report-contract.md | 2 +- plugins/diagnostics/README.md | 6 +++- 7 files changed, 93 insertions(+), 34 deletions(-) create mode 100644 AGENTS.md delete mode 100644 docs/development.md delete mode 100644 docs/migration-inventory.md create mode 100644 docs/plugins.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61743db --- /dev/null +++ b/AGENTS.md @@ -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//`. 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. diff --git a/README.md b/README.md index 3f26953..88a9451 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index 803ae15..0000000 --- a/docs/development.md +++ /dev/null @@ -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. diff --git a/docs/migration-inventory.md b/docs/migration-inventory.md deleted file mode 100644 index 7997a12..0000000 --- a/docs/migration-inventory.md +++ /dev/null @@ -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. diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 0000000..080ed30 --- /dev/null +++ b/docs/plugins.md @@ -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//`; 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//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// + 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`. diff --git a/docs/report-contract.md b/docs/report-contract.md index 933b59e..8e081e2 100644 --- a/docs/report-contract.md +++ b/docs/report-contract.md @@ -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 diff --git a/plugins/diagnostics/README.md b/plugins/diagnostics/README.md index e0d6120..3b59bf1 100644 --- a/plugins/diagnostics/README.md +++ b/plugins/diagnostics/README.md @@ -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.