NAME

project-doctor - Pre-release health check for Perl CPAN distributions

VERSION

0.02

SYNOPSIS

project-doctor [options] [PATH]

Options:
  --check NAMES    Run only the named checks (comma-separated)
  --skip  NAMES    Skip the named checks (comma-separated)
  --fix            Apply all fixes non-interactively
  --no-fix         Report only; never prompt for fixes
  --format FORMAT  Output format: text (default), json, tap
  --verbose, -v    Show per-finding detail for all checks
  --quiet,   -q    Suppress banner and passing checks
  --help,    -h    Show this help
  --man            Show full manual page

DESCRIPTION

Runs a suite of diagnostics against a Perl CPAN distribution and reports on tests, CI configuration, META validity, POD coverage, dependency declarations, licensing, GitHub Actions workflows, security hygiene, and CPAN upload readiness.

Fixable issues are listed at the end; the user is prompted (or fixes are applied automatically with --fix).

EXAMPLES

# Check the current directory
project-doctor

# Check a specific distribution
project-doctor ~/src/My-Dist

# Run only the Tests and POD checks
project-doctor --check=Tests,Pod

# JSON output for editor integration
project-doctor --format=json --no-fix

# CI usage: fail the build on any error
project-doctor --no-fix --format=tap

EXIT STATUS

0   No errors found
1   One or more errors found

CHECKS

In default execution order:

Tests           Test suite exists and passes
CI              CI configuration is present
GitHubActions   Workflow files validate cleanly
Meta            META.yml/json is present and complete
Pod             All modules have valid POD
Dependencies    Used modules are declared as prerequisites
License         LICENSE file is present and consistent with META
Security        strict/warnings present; no hardcoded credentials
CpanReadiness   Version format, Changes, MANIFEST, README present

LIMITATIONS

The fix context is built from PATH, not from the detected root. In the rare case where PATH is not the project root (e.g. a subdirectory), the Context may have a different root than Doctor used.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENSE

Copyright (C) 2026 Nigel Horne. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.