diff --git a/AGENT.md b/AGENT.md index faa07f0..a970ab4 100644 --- a/AGENT.md +++ b/AGENT.md @@ -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. diff --git a/README.md b/README.md index 0dc8d61..8140344 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/development.md b/docs/development.md index ccec821..c7db733 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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/`. diff --git a/tools/validate.jq b/tools/validate.jq deleted file mode 100644 index 7058d64..0000000 --- a/tools/validate.jq +++ /dev/null @@ -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 diff --git a/tools/validate.sh b/tools/validate.sh index 1e1b070..806c9b2 100755 --- a/tools/validate.sh +++ b/tools/validate.sh @@ -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" '' --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" '' --one >/dev/null 2>&1 || { echo "error: invalid report v1" >&2; exit 1; } echo "Valid report v1: $1" diff --git a/tools/validate.typ b/tools/validate.typ new file mode 100644 index 0000000..93ad23e --- /dev/null +++ b/tools/validate.typ @@ -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)