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

NAME

Test::CPAN::Health::Check::DeclaredDeps - Verify all runtime module dependencies are declared in META

SYNOPSIS

use Test::CPAN::Health::Check::DeclaredDeps;

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

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

DESCRIPTION

Scans all .pm and script files in the distribution for use MODULE and require MODULE statements, then cross-references the extracted module names against the runtime prerequisites declared in the distribution's META (or MYMETA) file.

A module is not flagged as undeclared when it is:

  • An all-lowercase Perl pragma (strict, warnings, autodie, utf8, feature, constant, etc.).

  • An internal module within this distribution (same namespace prefix).

  • A version string (require 5.014) -- starts with a digit.

  • A module known to be in Perl core for the declared minimum Perl version, detected via Module::CoreList when available.

  • A member of the hardcoded @ALWAYS_AVAILABLE list for cases where Module::CoreList is unavailable.

Score = 100 * (used_and_declared / total_used). Status: pass when all dependencies are declared; warn when score ≥ 80; fail otherwise.

LIMITATIONS

  • Requires a META or MYMETA file to provide the declared prerequisite list. If no META exists the check is skipped.

  • Dynamic require expressions (e.g. require $class) are not detected -- only static string forms.

  • POD code examples that contain use MODULE are excluded via a simple line-by-line POD state machine.

run

PURPOSE

Scan source files for use/require module statements and compare against the runtime prerequisites declared in META.

API SPECIFICATION

INPUT

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

OUTPUT

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

MESSAGES

Code  | Severity | Message                                      | Resolution
------+----------+----------------------------------------------+-----------
DD001 | SKIP     | No META file found                           | Run perl Makefile.PL first
DD002 | SKIP     | No source files to scan                      | Add .pm files under lib/
DD003 | PASS     | All N runtime dependencies are declared      |
DD004 | WARN     | N undeclared runtime dependencies found      | Add to PREREQ_PM / cpanfile
DD005 | FAIL     | N undeclared runtime dependencies found      | Add to PREREQ_PM / cpanfile

FORMAL SPECIFICATION

Pre:  dist isa Test::CPAN::Health::Distribution
      META or MYMETA file present (else skip)
Post: n_bad = 0         => status = pass  /\ score = 100
      n_bad > 0
        /\ score >= 80  => status = warn
        /\ score < 80   => status = fail

SIDE EFFECTS

Reads source files from disk. No network I/O.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::DeclaredDeps->new->run($dist);
if ($result->status ne 'pass') {
    print "Undeclared: ", join(', ', @{ $result->details }), "\n";
}

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENSE AND COPYRIGHT

Copyright (C) 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.