/ 
Test-CPAN-Health-0.1.0
/ Test::CPAN::Health::Check::Kwalitee

NAME

Test::CPAN::Health::Check::Kwalitee - Check CPANTS kwalitee indicators

SYNOPSIS

use Test::CPAN::Health::Check::Kwalitee;

my $check  = Test::CPAN::Health::Check::Kwalitee->new;
my $result = $check->run($dist);

printf "%s: %s\n", $result->status, $result->summary;

DESCRIPTION

Uses Module::CPANTS::Analyse to evaluate the distribution against the standard CPANTS kwalitee indicator set and converts the result into a 0-100 check score.

Experimental indicators (is_experimental = 1) are excluded from the score because they may change without notice and should not gate a distribution's health status. Core and extra indicators both count.

Score = (passed_non_experimental / total_non_experimental) * 100. Status thresholds: pass ≥ 80, warn ≥ 60, fail otherwise.

LIMITATIONS

  • Module::CPANTS::Analyse expects a directory laid out like an unpacked CPAN tarball. Fields like manifest_matches_dist may return false for a plain git working directory that lacks a MANIFEST file.

  • The _dangerous option is required when analysing a local directory rather than a downloaded distribution.

run

PURPOSE

Run the full CPANTS kwalitee analysis against the distribution and return a scored result.

API SPECIFICATION

INPUT

dist     Test::CPAN::Health::Distribution  required
context  Hashref                           optional

OUTPUT

Test::CPAN::Health::Result with check_id 'kwalitee'.

MESSAGES

Code  | Severity | Message                                       | Resolution
------+----------+-----------------------------------------------+-----------
KW001 | SKIP     | Module::CPANTS::Analyse is not installed      | cpanm Module::CPANTS::Analyse
KW002 | ERROR    | Module::CPANTS::Analyse failed: ...           | See error detail
KW003 | ERROR    | No kwalitee indicators found                  | Upgrade Module::CPANTS::Analyse
KW004 | PASS     | N of M kwalitee indicators passed (P%)        |
KW005 | WARN     | N of M kwalitee indicators passed (P%)        | Fix listed indicators
KW006 | FAIL     | N of M kwalitee indicators passed (P%)        | Fix listed indicators

FORMAL SPECIFICATION

-- Z schema (placeholder) --
KwaliteeOp
passed  : N
total   : N
score   : 0..100
-------------------------------------------------------
Module::CPANTS::Analyse unavailable  => status = skip
total = 0                            => status = error
score >= 80                          => status = pass
score >= 60                          => status = warn
score < 60                           => status = fail

SIDE EFFECTS

Reads all source files in the distribution. No network or subprocess I/O.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::Kwalitee->new->run($dist);
printf "Kwalitee: %d/100\n", $result->score;

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.