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

NAME

Test::CPAN::Health::Check::Complexity - Check cyclomatic complexity of subroutines

SYNOPSIS

use Test::CPAN::Health::Check::Complexity;

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

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

DESCRIPTION

Uses Perl::Metrics::Simple to compute the McCabe cyclomatic complexity of every subroutine in the distribution's .pm files. Subroutines with a complexity score above 20 are flagged as "too complex".

Score = round((1 - complex_subs / total_subs) * 100). Status thresholds: pass ≥ 90, warn ≥ 50, fail otherwise.

If no subroutines are found (e.g. a purely declarative module) the check passes at 100.

LIMITATIONS

  • Only .pm files are analysed; script files (.pl, bin/) are excluded because their top-level code is not part of a named subroutine.

  • Perl::Metrics::Simple uses PPI for parsing and may not handle all Perl syntax correctly.

run

PURPOSE

Measure McCabe complexity of all named subroutines and score by the fraction below the threshold.

API SPECIFICATION

INPUT

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

OUTPUT

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

MESSAGES

Code  | Severity | Message                                     | Resolution
------+----------+---------------------------------------------+-----------
CX001 | SKIP     | No .pm files found                          | Add lib/ modules
CX002 | PASS     | All N subroutines within complexity limit   |
CX003 | WARN     | N subroutine(s) exceed complexity limit     | Refactor subs
CX004 | FAIL     | Most subroutines exceed complexity limit    | Refactor subs

FORMAL SPECIFICATION

-- Z schema (placeholder) --
ComplexityOp
total_subs   : N
complex_subs : N
score        : 0..100
-------------------------------------------------------
total_subs = 0    => status = pass /\ score = 100
score >= 90       => status = pass
score >= 50       => status = warn
score < 50        => status = fail

SIDE EFFECTS

Invokes Perl::Metrics::Simple which performs in-process PPI parsing. No network or subprocess I/O.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::Complexity->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.