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

NAME

Test::CPAN::Health::Check::ReadmeSync - Check that a README exists and reflects the main module

SYNOPSIS

use Test::CPAN::Health::Check::ReadmeSync;

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

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

DESCRIPTION

Verifies that the distribution includes a non-trivial README file and that it mentions the distribution name, indicating it has not been left as a boilerplate stub.

Score breakdown:

0    No README file found at all
60   README found but very short (< 100 bytes) -- likely a placeholder
80   README found and non-trivial, but distribution name not mentioned
100  README found, non-trivial, and mentions the distribution name

LIMITATIONS

  • Only the content of the README is checked, not whether it is up-to-date with the current DESCRIPTION or SYNOPSIS in the POD.

  • The distribution name match is case-insensitive and converts :: to - before searching.

run

PURPOSE

Locate a README file and verify it is populated and references the distribution name.

API SPECIFICATION

INPUT

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

OUTPUT

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

MESSAGES

Code  | Severity | Message                                             | Resolution
------+----------+-----------------------------------------------------+-----------
RS001 | FAIL     | No README file found                                | Add README.md
RS002 | WARN     | README is very short (< 100 bytes)                  | Expand README
RS003 | WARN     | README does not mention the distribution name       | Update README
RS004 | PASS     | README found and mentions the distribution name     |

FORMAL SPECIFICATION

-- Z schema (placeholder) --
ReadmeSyncOp
dist_name  : String | undefined
readme     : FileName | undefined
content    : String
-------------------------------------------------------
readme = undefined          => status = fail /\ score = 0
#content < 100              => status = warn /\ score = 60
dist_name not in content    => status = warn /\ score = 80
dist_name in content        => status = pass /\ score = 100

SIDE EFFECTS

Reads at most one file from disk; no network I/O.

USAGE EXAMPLE

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

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.