metakraft/payload-doctor

Static security & correctness linter for Payload CMS. Zero-config, deterministic, ts-morph-based. Catches access-control gaps, unsafe Local API usage & richtext render risks. npx-runnable.

# payload-doctor Static **security & correctness linter for [Payload CMS](https://payloadcms.com)** — the TypeScript headless CMS. It scans your collections, access control, hooks, routes and config for known anti-patterns — the kind that AI coding agents and humans alike get wrong — and prints a **0–100 health score** with actionable findings. > **Note:** this is for **Payload CMS** (the framework). It does *not* inspect or > validate API request/response payloads (JSON/XML). If you came looking for that, > this isn't it. Think of it as a `react-doctor` for Payload. One command, no install: ```bash npx -y payload-doctor@latest . ``` ## Why Payload's **Local API bypasses access control by default** (`overrideAccess` is `true` unless you set it to `false`). It's the single most expensive footgun in a Payload app: a route can authenticate a user and still hand them someone else's records, because the collection's `access` functions never run. payload-doctor catches that and a dozen related issues before they reach production. ## Usage ```bash # scan the current project npx -y payload-doctor@latest . # show fix hints npx -y payload-doctor@latest . --verbose # machine-readable output for CI / dashboards npx -y payload-doctor@latest . --json # big report? show only the per-rule rollup npx -y payload-doctor@latest . --summary # print a suggested fix per rule (never modifies files) npx -y payload-doctor@latest . --fix # fail a CI job if the score drops below a threshold npx -y payload-doctor@latest . --min-score 80 # print the version npx -y payload-doctor@latest --version ``` **Recommended workflow:** run it → fix the errors first → re-run and watch the score climb. Keep a clean git state before applying fixes. Score bands: **75–100 great · 50–74 needs work ·