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

NAME

Test::CPAN::Health::Check::ReverseDeps - Count how many CPAN distributions depend on this one

SYNOPSIS

use Test::CPAN::Health::Check::ReverseDeps;

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

DESCRIPTION

Queries the MetaCPAN API to count how many other CPAN distributions declare a dependency on this distribution. A higher reverse-dependency count is a positive quality signal: widely-depended-upon code tends to be well-maintained.

The count is stored in data->{count} and is read from the runner context by the SecurityAdvisories check to scale the urgency of its messages.

Score brackets: 0 → 50 (warn), 1-9 → 75 (pass), 10-99 → 90 (pass), 100+ → 100 (pass).

LIMITATIONS

  • Results are accurate only for distributions that have been indexed on MetaCPAN. A purely local path will usually still match by dist name from the META file.

  • The count reflects CPAN metadata at query time and is cached for 24 h by the Runner's Test::CPAN::Health::Cache.

run

PURPOSE

Query MetaCPAN for the distribution's reverse-dependency count and return a scored result. The count is stored in data->{count}.

API SPECIFICATION

INPUT

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

OUTPUT

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

MESSAGES

Code  | Severity | Message                               | Resolution
------+----------+---------------------------------------+-----------
RD001 | SKIP     | Network checks disabled               | Remove --no-network
RD002 | SKIP     | Distribution name not available       | Add META.yml with name field
RD003 | ERROR    | MetaCPAN API error: ...               | Transient; retry
RD004 | WARN     | 0 reverse dependencies found          | Publish / promote the dist
RD005 | PASS     | N reverse dependencies found          |

FORMAL SPECIFICATION

-- Z schema (placeholder) --
ReverseDepsOp
count  : N
score  : {50, 75, 90, 100}
-------------------------------------------------------
count = 0          => score = 50  /\ status = warn
1 <= count < 10    => score = 75  /\ status = pass
10 <= count < 100  => score = 90  /\ status = pass
count >= 100       => score = 100 /\ status = pass

SIDE EFFECTS

Makes one HTTPS GET request to fastapi.metacpan.org.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::ReverseDeps->new->run($dist);
printf "Reverse deps: %d\n", $result->data->{count};

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.