payload-doctor 0.5.4

package/dist/cli.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const ts_morph_1 = require("ts-morph");
+const checks_1 = require("./checks");
+const project_1 = require("./checks/project");
+const score_1 = require("./score");
+const report_1 = require("./report");
+const suppress_1 = require("./suppress");
+const version_1 = require("./version");
+function parseArgs(argv) {
+    const o = {
+        target: '.',
+        verbose: false,
+        json: false,
+        list: false,
+        color: process.stdout.isTTY ?? false,
+        exitCode: true,
+        minScore: null,
+        help: false,
+        version: false,
+        summary: false,
+        fix: false,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case '--version':
+            case '-V':
+                o.version = true;
+                break;
+            case '--verbose':
+            case '-v':
+                o.verbose = true;
+                break;
+            case '--json':
+                o.json = true;
+                break;
+            case '--list':
+                o.list = true;
+                break;
+            case '--summary':
+                o.summary = true;
+                break;
+            case '--fix':
+                o.fix = true;
+                break;
+            case '--no-color':
+                o.color = false;
+                break;
+            case '--color':
+                o.color = true;
+                break;
+            case '--no-exit-code':
+                o.exitCode = false;
+                break;
+            case '--min-score': {
+                const raw = argv[++i];
+                const n = Number(raw);
+                if (raw === undefined || raw === '' || !Number.isFinite(n) || n < 0 || n > 100) {
+                    console.error(`Invalid --min-score value: ${raw ?? '(missing)'}. Expected a number between 0 and 100.`);
+                    process.exit(2);
+                }
+                o.minScore = n;
+                break;
+            }
+            case '--help':
+            case '-h':
+                o.help = true;
+                break;
+            default:
+                if (!a.startsWith('-'))
+                    positional.push(a);
+        }
+    }
+    if (positional[0])
+        o.target = positional[0];
+    return o;
+}
+const HELP = `payload-doctor v${version_1.VERSION} — static security & correctness auditor for Payload CMS
+
+Usage:
+  npx -y payload-doctor@latest [path] [options]
+
+Options:
+  -v, --verbose     show fix hints under each finding
+      --json        machine-readable JSON output
+      --list        list all checks and exit
+      --summary     show only the per-rule rollup, not every finding
+      --fix         print a suggested fix per rule (does not modify files)
+      --min-score N exit non-zero if the score is below N
+      --no-exit-code always exit 0 (useful in pre-commit while adopting)
+      --no-color    disable ANSI colors
+  -V, --version     print version and exit
+  -h, --help        show this help
+
+Suppress intentional cases with a comment on or above the line:
+  // payload-doctor-disable-next-line local-api-override-access
+  // payload-doctor-disable side-effect-in-get   (whole file; omit rule for all)
+
+Workflow: run it, fix errors first, re-run to watch the score climb.
+Score = max(0, 100 − 10·errors − 3·warnings); info findings don't affect it.
+Score bands: 75-100 great · 50-74 needs work · 0-49 critical.
+(10+ errors floor the score at 0 by design — watch the error/warning counts drop to gauge progress.)`;
+function listChecks() {
+    for (const ch of checks_1.ALL_CHECKS) {
+        console.log(`${ch.category.padEnd(12)} payload-doctor/${ch.id}\n             ${ch.describe}`);
+    }
+}
+function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    (0, report_1.setColor)(opts.color);
+    if (opts.version) {
+        console.log(`payload-doctor v${version_1.VERSION}`);
+        process.exit(0);
+    }
+    if (opts.help) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    if (opts.list) {
+        listChecks();
+        process.exit(0);
+    }
+    const root = path.resolve(opts.target);
+    if (!fs.existsSync(root)) {
+        console.error(`Path not found: ${opts.target}\n` +
+            'Point payload-doctor at an existing Payload project. From the project root, run it with ".".');
+        process.exit(2);
+    }
+    let project;
+    try {
+        project = new ts_morph_1.Project({
+            skipAddingFilesFromTsConfig: true,
+            compilerOptions: { allowJs: true, checkJs: false },
+        });
+        if (fs.statSync(root).isFile()) {
+            project.addSourceFileAtPath(root);
+        }
+        else {
+            project.addSourceFilesAtPaths([
+                `${root}/**/*.ts`,
+                `${root}/**/*.tsx`,
+                `${root}/**/*.js`,
+                `${root}/**/*.jsx`,
+                `!${root}/**/node_modules/**`,
+                `!${root}/**/dist/**`,
+                `!${root}/**/.next/**`,
+                `!${root}/**/build/**`,
+                `!${root}/**/*.d.ts`,
+            ]);
+        }
+    }
+    catch (err) {
+        console.error(`Failed to read the project at ${root}:\n  ${err instanceof Error ? err.message : String(err)}\n` +
+            'Make sure the path is a readable Payload project directory (or a single .ts/.tsx file).');
+        process.exit(2);
+    }
+    const files = project.getSourceFiles();
+    if (files.length === 0) {
+        console.error(`No .ts/.tsx/.js/.jsx files found under ${root}.\n` +
+            'Point payload-doctor at a Payload project root (where your collections/ and payload config live).');
+        process.exit(2);
+    }
+    const ctx = {
+        root,
+        rel: (abs) => path.relative(root, abs) || path.basename(abs),
+    };
+    const rawFindings = [];
+    for (const file of files) {
+        for (const check of checks_1.ALL_CHECKS) {
+            try {
+                rawFindings.push(...check.run(file, ctx));
+            }
+            catch {
+                // a single check throwing must not abort the whole scan
+            }
+        }
+    }
+    // cross-file checks (e.g. duplicate slugs across collections)
+    try {
+        rawFindings.push(...(0, project_1.projectChecks)(files, ctx));
+    }
+    catch {
+        // never let an aggregate check abort the scan
+    }
+    // inline suppression (// payload-doctor-disable...)
+    const fileTexts = new Map();
+    for (const file of files)
+        fileTexts.set(ctx.rel(file.getFilePath()), file.getFullText());
+    const { kept: findings, suppressed } = (0, suppress_1.applySuppressions)(rawFindings, fileTexts);
+    const score = (0, score_1.scoreFindings)(findings);
+    if (opts.json) {
+        console.log((0, report_1.renderJson)(findings, score, { root, filesScanned: files.length, suppressed }));
+    }
+    else {
+        console.log(`payload-doctor v${version_1.VERSION}\n`);
+        if (files.length === 0) {
+            console.log('No source files found. Point payload-doctor at your Payload project root.');
+        }
+        else if (findings.length === 0) {
+            const tail = suppressed > 0 ? ` (${suppressed} suppressed)` : '';
+            console.log(`Scanned ${files.length} files. No issues found. Score: 100/100${tail}`);
+        }
+        else {
+            console.log((0, report_1.renderText)(findings, score, { verbose: opts.verbose, suppressed, summaryOnly: opts.summary }));
+        }
+        if (opts.fix && findings.length > 0) {
+            const fixes = (0, report_1.renderFixes)(findings);
+            if (fixes)
+                console.log('\n' + fixes);
+        }
+    }
+    if (!opts.exitCode)
+        process.exit(0);
+    if (opts.minScore !== null && score.score < opts.minScore)
+        process.exit(1);
+    process.exit(score.counts.error > 0 ? 1 : 0);
+}
+main();

package/dist/fix.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixFor = fixFor;
+// Generic, copy-pasteable fix suggestions per rule. These are starting points,
+// not file-specific rewrites — payload-doctor never modifies your files.
+const FIXES = {
+    'local-api-override-access': "await payload.find({ collection, overrideAccess: false, user: req.user })",
+    'override-access-true-with-user': "// drop overrideAccess and pass the real user so access control runs",
+    'collection-missing-access': "access: {\n  read: () => true,\n  create: ({ req }) => Boolean(req.user),\n  update: ({ req }) => Boolean(req.user),\n  delete: ({ req }) => req.user?.role === 'admin',\n}",
+    'open-access-function': "read: ({ req }) => Boolean(req.user)  // not () => true",
+    'missing-owner-enforcement': "// beforeChange: data.owner = req.user.id\n// access.read:  ({ req }) => ({ owner: { equals: req.user?.id } })",
+    'user-writable-privileged-field': "access: { update: ({ req }) => req.user?.role === 'admin' }",
+    'cron-not-fail-closed': "if (req.headers.get('authorization') !== `Bearer ${process.env.CRON_SECRET}`)\n  return new Response('Unauthorized', { status: 401 })",
+    'side-effect-in-get': "export async function POST() { /* move the write here, or add an idempotency guard */ }",
+    'leaks-error-message': "console.error(err)  // log server-side\nreturn Response.json({ error: 'Internal error' }, { status: 500 })",
+    'hardcoded-secret': "secret: process.env.PAYLOAD_SECRET!  // and throw at startup if missing",
+    'wide-open-cors': "cors: ['https://yourdomain.com']",
+    'token-field-readable': "access: { read: () => false }",
+    'unsafe-richtext-render': "dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(html) }}",
+    'collection-missing-slug': "slug: 'posts',",
+    'hook-missing-return': "return data  // afterRead: return doc",
+    'admin-hidden-not-access': "access: { read: () => false },  // admin.hidden alone leaves it in the API",
+    'duplicate-slug': "// rename one collection to a unique slug",
+    'dependency-version-mismatch': "// pin all payload + @payloadcms/* deps to the same exact version",
+    'relationship-missing-relationTo': "{ name: 'author', type: 'relationship', relationTo: 'users' }",
+    'select-without-options': "{ name: 'status', type: 'select', options: [{ label: 'Draft', value: 'draft' }] }",
+    'duplicate-field-name': "// rename one of the two fields so names are unique within the level",
+    'auth-weak-config': "auth: { maxLoginAttempts: 5, lockTime: 600000, tokenExpiration: 7200 }",
+    'sensitive-data-logged': "// remove the log, or redact: console.log({ id: doc.id }) — never the secret itself",
+    'reserved-field-name': "// rename the field (Payload owns id/_id/createdAt/updatedAt/_status); no '.' or '$' in Mongo keys",
+    'excessive-max-depth': "maxDepth: 2,  // request deeper only where you actually need it",
+    'missing-index-on-filter-field': "{ name: 'email', type: 'email', index: true }",
+    'hook-n-plus-one': "const docs = await payload.find({ collection, where: { id: { in: ids } } })\n// then map over docs.docs instead of querying per item",
+    'circular-relationship': "// fine if intentional — just keep query depth small (depth: 1) to avoid populating the loop",
+};
+function fixFor(ruleId) {
+    return FIXES[ruleId];
+}

package/dist/report.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setColor = setColor;
+exports.rollupData = rollupData;
+exports.renderText = renderText;
+exports.renderFixes = renderFixes;
+exports.renderJson = renderJson;
+const version_1 = require("./version");
+const fix_1 = require("./fix");
+const COLOR = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    green: '\x1b[32m',
+};
+let useColor = true;
+function setColor(on) {
+    useColor = on;
+}
+function c(code, s) {
+    return useColor ? `${code}${s}${COLOR.reset}` : s;
+}
+const SEV_MARK = {
+    error: '✗',
+    warning: '!',
+    info: 'i',
+};
+function sevColor(sev) {
+    return sev === 'error' ? COLOR.red : sev === 'warning' ? COLOR.yellow : COLOR.blue;
+}
+const SEV_RANK = { error: 0, warning: 1, info: 2 };
+/** Aggregate findings per rule, sorted by severity then count. Shared by text + JSON. */
+function rollupData(findings) {
+    const byRule = new Map();
+    for (const f of findings) {
+        const a = byRule.get(f.ruleId) ?? { count: 0, files: new Set(), sev: f.severity, e: 0, w: 0, i: 0 };
+        a.count++;
+        a.files.add(f.file);
+        if (f.severity === 'error')
+            a.e++;
+        else if (f.severity === 'warning')
+            a.w++;
+        else
+            a.i++;
+        if (SEV_RANK[f.severity] < SEV_RANK[a.sev])
+            a.sev = f.severity;
+        byRule.set(f.ruleId, a);
+    }
+    return [...byRule.entries()]
+        .map(([ruleId, a]) => ({
+        ruleId,
+        severity: a.sev,
+        count: a.count,
+        files: a.files.size,
+        errors: a.e,
+        warnings: a.w,
+        infos: a.i,
+    }))
+        .sort((x, y) => SEV_RANK[x.severity] - SEV_RANK[y.severity] || y.count - x.count);
+}
+/** Compact per-rule summary lines with e/w/i breakdown. */
+function ruleRollup(findings) {
+    if (findings.length === 0)
+        return [];
+    const lines = [c(COLOR.bold, 'Summary by rule:')];
+    for (const r of rollupData(findings)) {
+        const mark = c(sevColor(r.severity), SEV_MARK[r.severity]);
+        const count = String(r.count).padStart(3);
+        const breakdown = c(COLOR.dim, `(${r.errors}e/${r.warnings}w/${r.infos}i)`);
+        lines.push(`  ${mark} ${count}  ${r.ruleId}  ${c(COLOR.dim, `in ${r.files} file(s)`)}  ${breakdown}`);
+    }
+    return lines;
+}
+function renderText(findings, score, opts) {
+    const lines = [];
+    // Summary by rule first, so the overview is visible without scrolling.
+    for (const l of ruleRollup(findings))
+        lines.push(l);
+    if (findings.length > 0)
+        lines.push('');
+    if (!opts.summaryOnly) {
+        // group by file
+        const byFile = new Map();
+        for (const f of findings) {
+            const arr = byFile.get(f.file) ?? [];
+            arr.push(f);
+            byFile.set(f.file, arr);
+        }
+        for (const [file, fs] of [...byFile.entries()].sort()) {
+            lines.push(c(COLOR.bold, file));
+            fs.sort((a, b) => a.line - b.line);
+            for (const f of fs) {
+                const loc = c(COLOR.dim, `${f.line}:${f.column}`);
+                const mark = c(sevColor(f.severity), `${SEV_MARK[f.severity]} ${f.severity}`);
+                lines.push(`  ${loc}  ${mark}  ${f.message}  ${c(COLOR.dim, f.ruleId)}`);
+                if (opts.verbose && f.hint) {
+                    lines.push(`        ${c(COLOR.dim, '↳ ' + f.hint)}`);
+                }
+            }
+            lines.push('');
+        }
+    } // end !summaryOnly
+    const bandLabel = score.band === 'great'
+        ? c(COLOR.green, 'Great')
+        : score.band === 'needs-work'
+            ? c(COLOR.yellow, 'Needs work')
+            : c(COLOR.red, 'Critical');
+    lines.push(c(COLOR.bold, `Score: ${score.score}/100`) +
+        `  ${bandLabel}  ` +
+        c(COLOR.dim, `(${score.counts.error} errors, ${score.counts.warning} warnings, ${score.counts.info} info)`));
+    if (opts.suppressed && opts.suppressed > 0) {
+        lines.push(c(COLOR.dim, `${opts.suppressed} finding(s) suppressed by inline comments.`));
+    }
+    return lines.join('\n');
+}
+/** A "Suggested fixes" section: one snippet per distinct rule present. */
+function renderFixes(findings) {
+    const order = [];
+    for (const f of findings)
+        if (!order.includes(f.ruleId))
+            order.push(f.ruleId);
+    const lines = [c(COLOR.bold, 'Suggested fixes (starting points — files are never modified):')];
+    let any = false;
+    for (const r of order) {
+        const group = findings.filter((f) => f.ruleId === r);
+        // Prefer a context-specific fix supplied by the check; else the generic template.
+        const fx = group.find((f) => f.fix)?.fix ?? (0, fix_1.fixFor)(r);
+        if (!fx)
+            continue;
+        any = true;
+        const first = group[0];
+        let where;
+        if (group.length === 1) {
+            where = `${first.file}:${first.line}`;
+        }
+        else {
+            const byFile = new Map();
+            for (const g of group)
+                byFile.set(g.file, (byFile.get(g.file) ?? 0) + 1);
+            const top = [...byFile.entries()].sort((a, b) => b[1] - a[1]);
+            const shown = top.slice(0, 4).map(([f, n]) => `${f} (${n})`);
+            const more = top.length > 4 ? `, +${top.length - 4} more` : '';
+            where = `${group.length}× in ${top.length} file${top.length === 1 ? '' : 's'} — ${shown.join(', ')}${more}`;
+        }
+        lines.push('');
+        lines.push(c(COLOR.dim, `# ${r}  (${where})`));
+        for (const l of fx.split('\n'))
+            lines.push('  ' + l);
+    }
+    if (!any)
+        return '';
+    return lines.join('\n');
+}
+function renderJson(findings, score, meta) {
+    return JSON.stringify({
+        tool: 'payload-doctor',
+        toolVersion: version_1.VERSION,
+        schema: 2,
+        root: meta.root,
+        filesScanned: meta.filesScanned,
+        suppressed: meta.suppressed ?? 0,
+        score: score.score,
+        band: score.band,
+        counts: score.counts,
+        summary: rollupData(findings),
+        findings,
+    }, null, 2);
+}

package/dist/score.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreFindings = scoreFindings;
+const WEIGHT = {
+    error: 10,
+    warning: 3,
+    info: 0,
+};
+function scoreFindings(findings) {
+    const counts = { error: 0, warning: 0, info: 0 };
+    let penalty = 0;
+    for (const f of findings) {
+        counts[f.severity]++;
+        penalty += WEIGHT[f.severity];
+    }
+    const score = Math.max(0, 100 - penalty);
+    const band = score >= 75 ? 'great' : score >= 50 ? 'needs-work' : 'critical';
+    return { score, band, counts };
+}

package/dist/suppress.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySuppressions = applySuppressions;
+const DIRECTIVE = /payload-doctor-(disable-next-line|disable-line|disable)\b([^\n\r]*)/;
+function parseRules(rest) {
+    const tokens = rest
+        .split(/[\s,]+/)
+        .map((t) => t.trim().replace(/^payload-doctor\//, ''))
+        .filter((t) => t.length > 0 && t !== '--');
+    if (tokens.length === 0 || tokens.includes('all'))
+        return 'all';
+    return new Set(tokens);
+}
+function mergeScope(existing, next) {
+    if (!existing)
+        return next;
+    if (existing === 'all' || next === 'all')
+        return 'all';
+    for (const r of next)
+        existing.add(r);
+    return existing;
+}
+function parseFile(text) {
+    const supp = { fileScope: null, lines: new Map() };
+    const lines = text.split(/\r?\n/);
+    lines.forEach((lineText, idx) => {
+        const m = lineText.match(DIRECTIVE);
+        if (!m)
+            return;
+        const kind = m[1];
+        const rules = parseRules(m[2] ?? '');
+        const lineNo = idx + 1;
+        if (kind === 'disable') {
+            supp.fileScope = mergeScope(supp.fileScope ?? undefined, rules);
+        }
+        else if (kind === 'disable-line') {
+            supp.lines.set(lineNo, mergeScope(supp.lines.get(lineNo), rules));
+        }
+        else {
+            supp.lines.set(lineNo + 1, mergeScope(supp.lines.get(lineNo + 1), rules));
+        }
+    });
+    return supp;
+}
+function scopeSuppresses(scope, ruleId) {
+    if (!scope)
+        return false;
+    if (scope === 'all')
+        return true;
+    return scope.has(ruleId);
+}
+function applySuppressions(findings, fileTexts) {
+    const cache = new Map();
+    const getSupp = (file) => {
+        if (cache.has(file))
+            return cache.get(file);
+        const text = fileTexts.get(file);
+        if (text === undefined)
+            return undefined;
+        const parsed = parseFile(text);
+        cache.set(file, parsed);
+        return parsed;
+    };
+    let suppressed = 0;
+    const kept = findings.filter((f) => {
+        const supp = getSupp(f.file);
+        if (!supp)
+            return true;
+        if (scopeSuppresses(supp.fileScope, f.ruleId) || scopeSuppresses(supp.lines.get(f.line), f.ruleId)) {
+            suppressed++;
+            return false;
+        }
+        return true;
+    });
+    return { kept, suppressed };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });