Add AGENT.md
This commit is contained in:
parent
6d53f479c2
commit
8b94966d26
|
|
@ -0,0 +1,235 @@
|
|||
# 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.
|
||||
Loading…
Reference in New Issue