NAME

App::Project::Doctor - Unified pre-release health check for Perl CPAN distributions

VERSION

0.01

SYNOPSIS

# Command line
project-doctor [--check=Tests,CI] [--skip=Meta] [--fix] [PATH]

# Programmatic
use App::Project::Doctor;

my $doctor = App::Project::Doctor->new(path => '/path/to/my-dist');
my $report = $doctor->run;
print $report->render_text;
exit $report->exit_code;

DESCRIPTION

Orchestrates a suite of diagnostic checks against a Perl CPAN distribution, combining App::Workflow::Lint, App::GHGen::Generator, App::makefilepl2cpanfile into a single interactive pre-upload tool.

Each enabled App::Project::Doctor::Check::* plugin receives an App::Project::Doctor::Context and returns a list of App::Project::Doctor::Finding objects which are collected into an App::Project::Doctor::Report.

CONSTRUCTOR

new( %args )

API SPECIFICATION

Input

path    : String    -- start path for root detection    default '.'
checks  : ArrayRef  -- check name suffixes to run       default all
skip    : ArrayRef  -- check names to exclude           default []
verbose : Bool                                          default 0

Output

Blessed hashref of type App::Project::Doctor.

ACCESSORS

path, checks, skip, verbose -- read-only.

METHODS

run

API SPECIFICATION

Input

None.

Output

App::Project::Doctor::Report.

MESSAGES

Code | Trigger                         | Resolution
-----|----------------------------------|----------------------------------------
DR01 | Cannot detect distribution root  | Run from within a distribution directory
DR02 | A check class cannot be loaded   | Install the check's prerequisites

CHECKS

In default execution order:

Tests           t/ exists, .t files present, prove passes
CI              At least one CI configuration present
GitHubActions   Workflow YAML validates via App::Workflow::Lint
Meta            META.yml/json parsed and complete
Pod             All .pm files have valid POD
Dependencies    Used modules declared as prerequisites
License         LICENSE file present and consistent with META
Security        strict/warnings everywhere; no hardcoded secrets
CpanReadiness   Version format, Changes, MANIFEST, README

run

Detects the distro root, instantiates all enabled checks, runs them in order, and returns an App::Project::Doctor::Report.

LIMITATIONS

Checks run sequentially; no parallelism.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

FORMAL SPECIFICATION

doctor

Doctor == { path : Path, checks : [Name], skip : [Name], verbose : Bool }

run : Doctor -> Report
run d ==
  let root    = detect_root (path d)
      ctx     = Context { root, verbose = verbose d }
      enabled = sort_by_order (checks d \\ skip d)
  in  Report { concat [ check c ctx | c <- enabled ] }

detect_root : Path -> Path | undefined
detect_root p == nearest ancestor of p containing a ROOT_MARKER

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.