reportist/AGENT.md

235 lines
4.2 KiB
Markdown

# AGENT.md — Reportist
## Mission
Reportist is a generic structured report renderer.
Its responsibility is strictly:
YAML / JSON
↓
Reportist
↓
Typst
↓
PDF
Reportist must remain independent from any specific diagnostic system,
organisation, incident database, or reporting workflow.
The existing `typst_reporter` repository may be used as a migration source,
but this repository is a clean implementation with intentionally defined
boundaries.
---
## Primary goals
1. Provide a stable structured report format.
2. Validate report input.
3. Render professional PDF reports using Typst.
4. Support configurable branding and presentation.
5. Remain usable as a standalone tool.
6. Preserve the sober corporate visual style of the original
`typst_reporter`.
---
## Non-goals
Reportist is NOT responsible for:
- collecting diagnostic information;
- interpreting Windows events;
- generating diagnostic conclusions;
- storing historical reports;
- managing incidents;
- knowing what Beffroi is;
- knowing what WinDiagnostics is.
Do not introduce dependencies on these concepts.
---
## Migration source
The existing `typst_reporter` project contains useful existing work.
When migrating from it, classify files before copying them.
Migrate:
- generic Typst templates;
- generic components;
- generic rendering scripts;
- generic styling;
- reusable validation logic.
Do NOT migrate:
- actual Beffroi reports;
- investigation history;
- diagnostic output;
- machine-specific information;
- hard-coded Beffroi branding.
Historical reports will eventually live in `beffroi-reports`.
---
## Input format
Reportist should define and document its input format.
Prefer:
schema/report.schema.json
Reports should carry an explicit schema version.
Conceptually:
schema_version
metadata
branding
title
summary
findings
recommendations
actions
appendices
Do not blindly implement this structure if the existing report format
already provides a better representation.
Preserve useful compatibility with existing reports where practical.
---
## Branding
Organisation-specific branding must be supplied as data/assets.
Do not hard-code:
- organisation name;
- logo;
- author;
- department;
- machine name;
- incident terminology.
A Beffroi report should be possible, but Reportist should work equally well
for an unrelated personal project.
---
## CLI
Aim for a simple interface.
For example:
reportist report.yaml
and:
reportist report.yaml --output report.pdf
During early development, a wrapper such as:
./render.sh report.yaml
is acceptable.
Do not make the CLI unnecessarily complex.
---
## Project structure
Prefer a structure approximately like:
src/
templates/
components/
schema/
examples/
tests/
assets/
Adapt this structure when there is a good reason.
Do not create empty architecture merely to satisfy this example.
---
## Examples
Maintain at least one synthetic example:
examples/example-report.yaml
It should exercise the important renderer functionality without containing
private or machine-specific information.
The example should render successfully as part of testing.
---
## Compatibility
Treat the report schema as a public interface.
Once versions are used by external report repositories, avoid breaking them
without:
- incrementing the schema version;
- documenting the change;
- providing a migration path when reasonable.
---
## Testing
At minimum test:
1. valid example report renders;
2. invalid input is rejected;
3. missing optional fields do not break rendering;
4. branding can be replaced;
5. output does not require external Beffroi repositories.
---
## Development principles
Prefer:
- explicit schemas;
- simple tooling;
- deterministic output;
- readable Typst;
- clear error messages;
- few dependencies.
Avoid:
- hidden coupling;
- absolute paths;
- report-specific hacks;
- duplicated rendering logic.
---
## Definition of success
A fresh clone of Reportist can render its example PDF without:
- WinDiagnostics;
- win-diagnostics;
- beffroi-reports;
- beffroi-reporting.
If another project needs to know Reportist internals in order to produce a
report, improve the input contract instead.