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

NAME

Test::CPAN::Health::Check::Perlcritic - Run Perl::Critic and report policy violations

SYNOPSIS

use Test::CPAN::Health::Check::Perlcritic;

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

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

DESCRIPTION

Runs Perl::Critic at severity 3 against every .pm and .pl source file in the distribution. Score = round((clean_files / total_files) * 100).

Status thresholds: pass ≥ 90 %, warn ≥ 50 %, fail below 50 %.

LIMITATIONS

  • No .perlcriticrc from the distribution under analysis is honoured; the check always runs at the fixed severity level to ensure comparable scores across distributions.

  • Files that cannot be parsed by PPI (Perl::Critic's parser) are skipped with a warning and excluded from the score calculation.

run

PURPOSE

Critique all source files at severity 3 and return a scored Result reflecting the fraction that pass without violations.

API SPECIFICATION

INPUT

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

OUTPUT

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

MESSAGES

Code  | Severity | Message                                     | Resolution
------+----------+---------------------------------------------+-----------
CR001 | SKIP     | No source files found                       | Add source files
CR002 | PASS     | All N files pass Perl::Critic at sev 3     |
CR003 | WARN     | N of M files have policy violations         | Fix violations
CR004 | FAIL     | Most files have Perl::Critic violations     | Fix violations

FORMAL SPECIFICATION

-- Z schema (placeholder) --
PerlcriticOp
total_files  : N
clean_files  : N
score        : 0..100
-------------------------------------------------------
total_files = 0    => status = skip
score >= 90        => status = pass
score >= 50        => status = warn
score < 50         => status = fail

SIDE EFFECTS

Invokes Perl::Critic which performs in-process PPI parsing of source files. No network or subprocess I/O.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::Perlcritic->new->run($dist);
print $result->summary;

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.