dart_pdf_linter

A tiny CLI tool to lint PDF files. It inspects page boxes and common pitfalls so you can catch production issues early.

What it checks

For each PDF file, the linter reports:

• Presence of MediaBox, TrimBox, and BleedBox
• Empty boxes (zero width/height)
• Mismatched page counts between media and trim boxes
• Pages where TrimBox == MediaBox
• Pages with non‑zero rotation

It also summarizes unique page sizes it encounters (in millimeters):

• Aggregated list of Mediaboxes
• Aggregated list of Trimboxes

Requirements

• Dart SDK: >= 3.9.2
• Poppler pdfinfo must be available on your system PATH (used via a local service wrapper)
  • macOS (Homebrew): brew install poppler
  • Ubuntu/Debian: sudo apt-get install poppler-utils
  • Fedora: sudo dnf install poppler-utils

Installation

Option A — Using the repository script (if available on your platform):

./install       # normal install
# or
./install.dev   # development install (if you prefer symlinks)

Option B — Activate globally from path:

dart pub global activate --source path /path/to/dart_pdf_linter
# Make sure your pub cache bin is on PATH, e.g.:
# export PATH="$PATH:${HOME}/.pub-cache/bin"

This exposes both executables: pdf_linter and dart_pdf_linter.

Usage

pdf_linter [-R] <path>

• -R — recurse into subdirectories
• <path> — a file or directory to scan

Examples:

# Lint all PDFs in a directory (non-recursive)
pdf_linter ./assets/pdfs

# Lint all PDFs recursively
pdf_linter -R ./assets

You can use the alternative entrypoint dart_pdf_linter with the same arguments.

Output

• For clean files, their paths are written to stdout.
• Problems are listed to stderr under the offending file path, for example:

/path/to/file.pdf
  - has no trimboxes
  - has 1 empty mediaboxes
  - page 3 : trimbox equals mediabox (0 0 595 842)

At the end of the run, unique sizes are summarized (stdout):

Mediaboxes:
  - 210 x 297 mm
  - 148 x 210 mm
Trimboxes:
  - 210 x 297 mm

Note: currently the tool does not set a non-zero exit code for findings; it reports issues via stderr while exiting with code 0.

Tips

• If no output appears, verify that pdfinfo is installed and available on PATH.
• Hidden files are ignored; only files with .pdf extension are inspected.

License

This project is licensed under the terms of the LICENSE file included in the repository.

Changelog

0.0.4 - 2025-11-21

Changed

• Version bump from 0.0.3 to 0.0.4 (test -> 1.28.0 (was 1.27.0)).

0.0.3 - 2025-11-11

Changed

• Version bump from 0.0.2 to 0.0.3 (test -> 1.27.0 (was 1.26.3)).

0.0.2 - 2025-11-11

• Second version.

0.0.1 - 2025-10-28

• Initial version.