# 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](https://metacpan.org/pod/App%3A%3AWorkflow%3A%3ALint), [App::GHGen::Generator](https://metacpan.org/pod/App%3A%3AGHGen%3A%3AGenerator), [App::makefilepl2cpanfile](https://metacpan.org/pod/App%3A%3Amakefilepl2cpanfile)
into a single interactive pre-upload tool.

Each enabled `App::Project::Doctor::Check::*` plugin receives an
[App::Project::Doctor::Context](https://metacpan.org/pod/App%3A%3AProject%3A%3ADoctor%3A%3AContext) and returns a list of
[App::Project::Doctor::Finding](https://metacpan.org/pod/App%3A%3AProject%3A%3ADoctor%3A%3AFinding) objects which are collected into an
[App::Project::Doctor::Report](https://metacpan.org/pod/App%3A%3AProject%3A%3ADoctor%3A%3AReport).

# 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](https://metacpan.org/pod/App%3A%3AProject%3A%3ADoctor%3A%3AReport).

### 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](https://metacpan.org/pod/App%3A%3AProject%3A%3ADoctor%3A%3AReport).

# 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.