/ 
Test-CPAN-Health-0.1.0
/ cpan-health

NAME

cpan-health - Analyse a CPAN distribution and report a weighted health score

VERSION

0.01

SYNOPSIS

cpan-health [options] [TARGET]

TARGET is a local filesystem path (default: .), a CPAN dist name such as
C<LWP-UserAgent>, or a Perl module name such as C<LWP::UserAgent>.

Options:
  -f, --format FORMAT         Output format: terminal (default), json, html, tap, markdown
      --check NAMES           Run only the named checks (comma-separated check ids)
      --skip  NAMES           Skip the named checks (comma-separated check ids)
      --no-network            Disable all network-dependent checks
      --no-cover              Disable Devel::Cover (the test-coverage check is slow)
      --severity N            Perl::Critic severity level 1-5 (default: 3)
      --min-score N           Exit 1 if overall score is below N (default: 0)
      --cache-dir DIR         Override the default cache directory
  -o, --output FILE           Write the report to FILE instead of STDOUT
  -q, --quiet                 Suppress banners and informational messages
      --list-checks           Print all available checks and exit
      --history               Show score history for TARGET and exit
      --badge                 Print a shields.io badge URL after the report
      --github-annotations    Emit GitHub Actions annotation lines (::error/::warning)
      --ignore-abandoned MOD  Comma-separated modules to exclude from abandoned-deps check
  -h, --help                  Show this help
      --man                   Show the full manual page
  -V, --version               Print the version number and exit

DESCRIPTION

cpan-health runs a configurable battery of checks against a CPAN distribution and reports a weighted health score out of 100.

Checks cover: semantic versioning, META validity, licensing, minimum Perl version, POD coverage, documentation quality, example scripts, benchmarks, Perl::Critic violations, code complexity, duplicate code, deprecation warnings, test coverage, kwalitee, CI configuration, stale and abandoned dependencies, known CVEs (via CPAN::Audit), CPAN Testers pass rate, and reverse dependency count.

The overall score is the weighted mean of per-check scores. Two hard caps apply: a failing SecurityAdvisories check caps the score at 60; a failing CPANTesters check caps it at 75.

EXAMPLES

# Analyse the current directory
cpan-health

# Analyse a specific local checkout
cpan-health ~/src/LWP-UserAgent-6.77

# Analyse by CPAN dist name (downloads and unpacks automatically)
cpan-health LWP-UserAgent

# Analyse by module name, skipping all network-dependent checks
cpan-health --no-network LWP::UserAgent

# JSON output for editor or CI integration
cpan-health --format=json LWP-UserAgent

# Fail the build if the score drops below 80
cpan-health --min-score=80 --no-cover My-Dist

# TAP output -- pipe into a test harness
cpan-health --format=tap My-Dist | prove --stdin

# Run only the security and versioning checks
cpan-health --check=security_advisories,sem_ver My-Dist

# Skip the slow coverage and network checks
cpan-health --no-cover --no-network .

EXIT STATUS

0   Score >= --min-score (or no threshold set); analysis completed normally
1   Score < --min-score, or a fatal error was encountered
2   Invalid arguments

CHECKS

Check ids for use with --check and --skip:

sem_ver               Semantic versioning (weight 3)
security_advisories   Known CVEs via CPAN::Audit (weight 10; hard cap 60)
cpan_testers          CPAN Testers pass rate (weight 8; hard cap 75)
meta_json             META.json/yml validity (weight 5)
license               SPDX licence declaration (weight 4)
min_perl              Minimum Perl version declaration (weight 3)
pod_coverage          POD coverage (weight 5)
doc_quality           Documentation quality (weight 4)
perlcritic            Perl::Critic violations (weight 6)
complexity            Code complexity via Perl::Metrics::Simple (weight 4)
test_coverage         Test coverage via Devel::Cover (weight 7)
kwalitee              CPANTS kwalitee metrics (weight 5)
ci_config             CI configuration presence (weight 4)
stale_deps            Stale dependencies (weight 5)
abandoned_deps        Abandoned dependencies (weight 5)
reverse_deps          Reverse dependency count (weight 2)
duplicate_code        Duplicate code detection (weight 3)
deprecations          Deprecated module usage (weight 4)
examples              Example scripts present (weight 2)
benchmarks            Benchmark scripts present (weight 1)

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENSE AND COPYRIGHT

Copyright (C) 2025-2026 Nigel Horne.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.