Preflight Reports

Compliance, Document inspection, Automation

Overview

PDFlibPas can run its built-in PDF/A and PDF/UA-1 file-compliance checks against an external PDF and turn the result into reusable report output. Use the report APIs when an application or build pipeline needs the same diagnostics as CheckFileCompliance, but does not want to manage string-list handles directly.

The report pipeline is intentionally layered. CheckFileCompliance remains the low-level API that returns issue-list handles. CreatePreflightReport formats the selected checks into a stable plain-text body. CreatePreflightReportEx converts that same text report to text, JSON, HTML, or CSV so all formats share the same pass/fail status and issue count.

Library APIs

CheckFileCompliance	Runs one selected compliance check against a PDF file and returns `0` for pass or a StringListID containing issue lines.
CreatePreflightReport	Runs PDF/A, PDF/UA-1, or both checks and returns a plain-text report with header metadata, one section per check, and a final summary.
CreatePreflightReportEx	Returns the same report in text (`0`), JSON (`1`), HTML (`2`), or CSV (`3`) format. Unknown format values fall back to text.
SavePreflightReport	Writes the plain-text report as UTF-8 and creates the parent directory when needed.
SavePreflightReportEx	Writes a text, JSON, HTML, or CSV report as UTF-8 and creates the parent directory when needed.
ComparePreflightReports	Compares two plain-text reports, ignores volatile `Generated:` timestamp lines, and returns a compact diff only when stable content changed.

Format Contract

Text	The canonical report body. It contains `Generated`, `Input`, `Checks`, `Issue mode`, one section for each selected check, and a `Summary` block with `Total issues` and `Result`.
JSON	A single object with `title`, `generated`, `input`, `checks`, `issueMode`, `sections`, and `summary`. Each section has a name, status, and issue-string array.
HTML	A standalone UTF-8 HTML document. The text report is HTML-escaped and displayed inside a preformatted block, so report content is visible without being interpreted as markup.
CSV	Rows use the fixed columns `kind,section,status,code,message`. `meta` rows carry header fields, `check` rows carry PASS/FAIL section status, `issue` rows split numeric issue codes from messages, and `summary` rows carry the final totals.

Compliance Selection

The report APIs use a bit mask for ComplianceTests: 1 selects PDF/A, 2 selects PDF/UA-1, and 3 selects both. Passing 0 also runs both checks. Options currently uses bit 1 to stop each selected check after its first issue; pass 0 to collect all reported issues.

Command-Line Demo

The Delphi PreflightReport console demo shows the report workflow without adding application-specific UI. It can validate a single PDF, generate formatted output, compare a new text report against a baseline, or batch-process a directory.

PreflightReport.exe --input "C:\PDFs\invoice.pdf" --output "C:\Reports\invoice.preflight.txt"
PreflightReport.exe --input "C:\PDFs\invoice.pdf" --output "C:\Reports\invoice.preflight.json" --json
PreflightReport.exe --input "C:\PDFs\invoice.pdf" --output "C:\Reports\invoice.preflight.csv" --format csv
PreflightReport.exe --input "C:\PDFs\invoice.pdf" --output "C:\Reports\invoice.preflight.txt" --compare "C:\Baselines\invoice.preflight.txt"
PreflightReport.exe --input-dir "C:\PDFs" --output-dir "C:\Reports" --recursive --format html

Single-file mode returns exit code 0 when the selected checks report no issues, 1 for command-line or runtime errors, and 2 when any issue is reported or the baseline comparison differs. Directory mode writes one <basename>.preflight.<ext> file per PDF and adds a preflight-summary.csv file with source path, pass/fail status, issue count, and report path.

Comparison Notes

ComparePreflightReports is defined for plain-text reports. It should be fed the baseline text report and the newly generated text report, even when the human-facing output for the same run is JSON, HTML, or CSV. The comparator normalises Generated: lines because timestamps change on every run; all other stable lines are compared in order with a small look-ahead window to keep insertion and deletion diffs readable.