refactor: validate reports with typst
Reportist CI All report validation and rendering checks passed.
Beffroi/reportist/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-09-16 01:20:17 +02:00
parent a82bda2b4f
commit 5902c6bc43
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
6 changed files with 77 additions and 32 deletions

View File

@ -204,8 +204,7 @@ At minimum test:
## Development principles
Reportist's production interface must be Make, shell, and Typst, with jq only
where shell needs structured JSON handling. Python may exist only in `tests/`,
Reportist's production interface must be Make, shell, and Typst. Python may exist only in `tests/`,
must run through a uv-managed virtual environment, and must not be called by
production validation or rendering.

View File

@ -13,7 +13,7 @@ Beffroi-specific repositories.
## Requirements
Runtime rendering requires Bash, jq, Typst 0.15 or newer, standard POSIX
Runtime rendering requires Bash, Typst 0.15 or newer, standard POSIX
utilities, and the fonts selected by the report. The examples use DejaVu Sans
and DejaVu Sans Mono.

View File

@ -22,8 +22,8 @@ content, and rendering from a standalone component copy.
## Contract maintenance
`schema/report.schema.json` is the public report interface. Keep the jq
production validator, Typst assertions, examples, and test oracle aligned with
`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.
@ -38,4 +38,4 @@ PDF bytes.
Reportist stays generic. Do not add diagnostic interpretation, Beffroi branding,
incident storage, publication, or packaging. Production validation and rendering
remain shell, jq, and Typst based; Python stays under `tests/`.
remain shell and Typst based; Python stays under `tests/`.

View File

@ -1,23 +0,0 @@
def keys_allowed($allowed): type=="object" and ((keys-$allowed)|length)==0;
def text: type=="string" and test("\\S");
def portable: text and (startswith("/")|not) and (contains("\\")|not) and (contains(":")|not) and ([split("/")[]|select(.=="" or .=="." or .=="..")] | length)==0;
def strings: type=="array" and length>0 and all(.[];text);
def block:
keys_allowed(["type","text","items","title","kind","content"]) and
if .type=="text" or .type=="code" then keys_allowed(["type","text"]) and (.text|text)
elif .type=="bullets" or .type=="steps" then keys_allowed(["type","items"]) and (.items|strings)
elif .type=="callout" then . as $b | keys_allowed(["type","title","kind","text"]) and (.text|text) and ((.title//"x")|text) and (["info","low","medium","high","critical","warning","ok","success","unanalysed"]|index($b.kind//"info")!=null)
elif .type=="subsection" then keys_allowed(["type","title","content"]) and (.title|text) and (.content|type=="array" and length>0 and all(.[];block))
else false end;
def section: keys_allowed(["title","content"]) and (.title|text) and (.content|type=="array" and length>0 and all(.[];block));
def valid:
keys_allowed(["schema_version","title","subtitle","id","report_type","status","severity","metadata","branding","summary","closing","timeline","findings","sections","appendices","actions_title","actions","provenance"]) and
.schema_version==1 and (.title|text) and (.metadata|type=="object") and (.metadata.Date|type=="string" and test("^[0-9]{4}-[0-9]{2}-[0-9]{2}$")) and (.metadata.Author|text) and
((.report_type//"technical") as $v|["technical","briefing"]|index($v)!=null) and
((.severity//"info") as $v|["info","low","medium","high","critical","warning","ok","success","unanalysed"]|index($v)!=null) and
((.branding//{})|keys_allowed(["organization","logo","theme"]) and ((.organization//"x")|text) and ((.logo//"x")|portable) and
((.theme//{})|keys_allowed(["font","mono_font","ink","muted","line","paper_soft","accent","info","warning","critical","success"]) and
all(to_entries[]; if (.key=="font" or .key=="mono_font") then (.value|text) else (.value|type=="string" and test("^#[0-9a-fA-F]{6}$")) end))) and
((.sections//[])|type=="array" and all(.[];section)) and ((.appendices//[])|type=="array" and all(.[];section)) and
((.findings//[]) as $f | ($f|type)=="array" and all($f[];keys_allowed(["id","title","severity","status","evidence","assessment","evidence_refs"]) and (.title|text)) and ([$f[]|select(.id).id]|length)==([$f[]|select(.id).id]|unique|length));
valid

View File

@ -5,7 +5,6 @@ set -euo pipefail
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P); input=$(realpath "$1")
case $input in *.json) format=json;; *.yaml|*.yml) format=yaml;; *) echo "error: expected YAML or JSON" >&2; exit 1;; esac
temp=$(mktemp -d "${TMPDIR:-/tmp}/reportist-validate.XXXXXXXX"); trap 'rm -rf "$temp"' EXIT
cp "$input" "$temp/report.$format"; cp "$root/tools/report-value.typ" "$temp/report-value.typ"
typst query --root "$temp" --input "report=report.$format" --input "format=$format" "$temp/report-value.typ" '<report-data>' --field value --one >"$temp/parsed.json" 2>/dev/null || { echo "error: unable to parse report" >&2; exit 1; }
jq -e -f "$root/tools/validate.jq" "$temp/parsed.json" >/dev/null || { echo "error: invalid report v1" >&2; exit 1; }
cp "$input" "$temp/report.$format"; cp "$root/tools/validate.typ" "$temp/validate.typ"
typst query --root "$temp" --input "report=report.$format" --input "format=$format" "$temp/validate.typ" '<validated>' --one >/dev/null 2>&1 || { echo "error: invalid report v1" >&2; exit 1; }
echo "Valid report v1: $1"

70
tools/validate.typ Normal file
View File

@ -0,0 +1,70 @@
#let file = sys.inputs.at("report")
#let format = sys.inputs.at("format")
#let report = if format == "json" { json(file) } else { yaml(file) }
#let nonempty(value) = type(value) == str and value.match(regex("\\S")) != none
#let keys-allowed(value, allowed) = type(value) == dictionary and value.keys().all(key => key in allowed)
#let portable(value) = (
nonempty(value) and
not value.starts-with("/") and
not value.contains("\\") and
not value.contains(":") and
value.split("/").all(part => part not in ("", ".", ".."))
)
#let values = ("info", "low", "medium", "high", "critical", "warning", "ok", "success", "unanalysed")
#let validate-block(item) = {
assert(type(item) == dictionary, message: "content block must be an object")
let kind = item.at("type", default: none)
if kind in ("text", "code") {
assert(keys-allowed(item, ("type", "text")) and nonempty(item.at("text", default: none)), message: "invalid text/code block")
} else if kind in ("bullets", "steps") {
let items = item.at("items", default: none)
assert(keys-allowed(item, ("type", "items")) and type(items) == array and items.len() > 0 and items.all(nonempty), message: "invalid list block")
} else if kind == "callout" {
assert(keys-allowed(item, ("type", "title", "kind", "text")) and nonempty(item.at("text", default: none)) and
nonempty(item.at("title", default: "x")) and item.at("kind", default: "info") in values, message: "invalid callout block")
} else if kind == "subsection" {
let content = item.at("content", default: none)
assert(keys-allowed(item, ("type", "title", "content")) and nonempty(item.at("title", default: none)) and
type(content) == array and content.len() > 0, message: "invalid subsection block")
for child in content { validate-block(child) }
} else { assert(false, message: "unsupported content block") }
}
#let validate-section(section) = {
assert(keys-allowed(section, ("title", "content")) and nonempty(section.at("title", default: none)), message: "invalid section")
let content = section.at("content", default: none)
assert(type(content) == array and content.len() > 0, message: "section content must not be empty")
for item in content { validate-block(item) }
}
#assert(keys-allowed(report, ("schema_version", "title", "subtitle", "id", "report_type", "status", "severity", "metadata", "branding", "summary", "closing", "timeline", "findings", "sections", "appendices", "actions_title", "actions", "provenance")), message: "unsupported report field")
#assert(report.at("schema_version", default: none) == 1, message: "unsupported or missing schema_version")
#assert(nonempty(report.at("title", default: none)), message: "title must be a non-empty string")
#let report-metadata = report.at("metadata", default: none)
#assert(type(report-metadata) == dictionary and nonempty(report-metadata.at("Date", default: none)) and nonempty(report-metadata.at("Author", default: none)), message: "metadata.Date and metadata.Author are required")
#assert(report-metadata.Date.match(regex("^[0-9]{4}-[0-9]{2}-[0-9]{2}$")) != none, message: "metadata.Date must use YYYY-MM-DD")
#assert(report.at("report_type", default: "technical") in ("technical", "briefing"), message: "unsupported report_type")
#assert(report.at("severity", default: "info") in values, message: "unsupported severity")
#let branding = report.at("branding", default: (:))
#assert(keys-allowed(branding, ("organization", "logo", "theme")), message: "invalid branding")
#assert(nonempty(branding.at("organization", default: "x")), message: "invalid branding organization")
#assert(portable(branding.at("logo", default: "x")), message: "invalid branding logo path")
#let theme = branding.at("theme", default: (:))
#assert(keys-allowed(theme, ("font", "mono_font", "ink", "muted", "line", "paper_soft", "accent", "info", "warning", "critical", "success")), message: "invalid theme field")
#for pair in theme.pairs() {
if pair.first() in ("font", "mono_font") { assert(nonempty(pair.last()), message: "invalid theme font") }
else { assert(type(pair.last()) == str and pair.last().match(regex("^#[0-9a-fA-F]{6}$")) != none, message: "invalid theme color") }
}
#for section in report.at("sections", default: ()) { validate-section(section) }
#for section in report.at("appendices", default: ()) { validate-section(section) }
#let findings = report.at("findings", default: ())
#let finding-ids = findings.filter(item => "id" in item).map(item => item.id)
#assert(finding-ids.dedup().len() == finding-ids.len(), message: "duplicate finding ID")
#for finding in findings {
assert(keys-allowed(finding, ("id", "title", "severity", "status", "evidence", "assessment", "evidence_refs")) and nonempty(finding.at("title", default: none)), message: "invalid finding")
}
#metadata(true) <validated>