/ 
Test-CPAN-Health-0.1.0
/ Test::CPAN::Health::Runner

NAME

Test::CPAN::Health::Runner - Orchestrate health checks against a distribution

SYNOPSIS

use Test::CPAN::Health::Runner;

my $runner = Test::CPAN::Health::Runner->new(
    checks => \@check_objects,
    cache  => $cache,
);

my $report = $runner->run($distribution);

DESCRIPTION

The Runner iterates over an ordered list of Test::CPAN::Health::Check objects, invokes each against a Test::CPAN::Health::Distribution, wraps any exceptions so a single failing check cannot abort the run, and collects the Test::CPAN::Health::Result objects into a Test::CPAN::Health::Report.

Context propagation: after each check completes its result is stored, and subsequent checks can inspect previously-completed results via the context hashref passed to run. This is how ReverseDeps count reaches SecurityAdvisories to scale its weight.

LIMITATIONS

  • Checks run sequentially. Parallel execution via Parallel::ForkManager is planned for a future release.

  • A check that calls exit directly will terminate the entire run.

run

PURPOSE

Execute all configured checks against the given distribution and return a populated Test::CPAN::Health::Report.

Each check is wrapped in an eval block: exceptions produce an error-status Result rather than aborting the run. Checks may return undef to indicate they are not applicable; those are silently skipped.

API SPECIFICATION

INPUT

dist  Test::CPAN::Health::Distribution  required

OUTPUT

Test::CPAN::Health::Report object with all results attached.

MESSAGES

Code  | Severity | Message                              | Resolution
------+----------+--------------------------------------+------------------------
RUN01 | WARNING  | Check {id} failed with exception {e} | Fix check or report bug

FORMAL SPECIFICATION

-- Z schema (placeholder) --
RunOp
checks      : seq Check
dist        : Distribution
report!     : Report
-------------------------------------------------------
#report!.results <= #checks
forall c : checks @
  (exists r : report!.results @ r.check_id = c.id)
  \/ c returned undefined

SIDE EFFECTS

Runs each check, which may have network, filesystem, and subprocess side effects. Writes check results to the cache if a cache is configured.

USAGE EXAMPLE

my $report = $runner->run($dist);
printf "%d checks run\n", scalar @{$report->results};

AUTHOR

Nigel Horne, <njh at 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.