235 lines
4.2 KiB
Markdown
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. |