Document Reportist plugin contract and agent guidance
This commit is contained in:
parent
b268af7cb7
commit
6f29f59d54
|
|
@ -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.
|
||||
20
README.md
20
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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`.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue