reportist/docs/development.md

1.5 KiB

Development

This document covers contributor workflows for Reportist. Rendering and report authoring are documented in the main README and report contract.

Test environment

Tests require uv and Typst. test.sh creates .venv and synchronizes the pinned packages from requirements.txt, and invokes Python only from that environment.

./test.sh

Poppler's pdfinfo and pdftotext enable additional pagination and extracted text checks. Those checks are skipped when Poppler is unavailable.

The suite covers JSON and YAML input, contract failures, optional fields, replaceable branding, asset safety, overwrite behavior, pagination, extracted content, and rendering from a standalone component copy.

Contract maintenance

schema/report.schema.json is the public report interface. Keep the Typst production validator, template assertions, examples, and test oracle aligned with the schema. Preserve version 1 compatibility or introduce a documented new version and migration path.

Visual changes

Exercise all supported content blocks and inspect representative PDFs after changing templates, typography, colors, spacing, headers, footers, or pagination. Record the Typst version and installed fonts because they can affect layout and PDF bytes.

Repository boundaries

Reportist stays generic. Do not add diagnostic interpretation, Beffroi branding, incident storage, publication, or packaging. Production validation and rendering remain shell and Typst based; Python stays under tests/.