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

NAME

Test::CPAN::Health::Check::VersionSync - Check that all .pm files declare the same $VERSION

SYNOPSIS

use Test::CPAN::Health::Check::VersionSync;

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

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

DESCRIPTION

Scans all .pm files under lib/ for $VERSION declarations and verifies that every file that declares a version uses the same value as the distribution version reported in the META file.

Files that do not declare $VERSION at all are not penalised (they may intentionally inherit a version from a parent namespace).

Score = (in-sync files / files-with-version) * 100. Status: pass ≥ 90, warn ≥ 50, fail otherwise.

LIMITATIONS

  • Only the first our $VERSION = '...'; line in each file is checked; dynamic version assignment (e.g. via version::-new>) is not supported.

  • The META version is used as the canonical source; if no META file is present the check is skipped.

run

PURPOSE

Compare the $VERSION declared in each .pm file against the distribution version from META, reporting any files that are out of sync.

API SPECIFICATION

INPUT

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

OUTPUT

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

MESSAGES

Code  | Severity | Message                                        | Resolution
------+----------+------------------------------------------------+-----------
VS001 | SKIP     | No META file found                             | Add META file
VS002 | SKIP     | No .pm files found                             | Add lib/ modules
VS003 | SKIP     | META version not available                     | Add version to META
VS004 | PASS     | All N file(s) with $VERSION in sync            |
VS005 | PASS     | No .pm files declare $VERSION                  |
VS006 | WARN     | N file(s) have mismatched $VERSION             | Update $VERSION
VS007 | FAIL     | Most files have mismatched $VERSION            | Update $VERSION

FORMAL SPECIFICATION

-- Z schema (placeholder) --
VersionSyncOp
meta_ver   : String | undefined
files      : seq FileName
mismatched : seq FileName
-------------------------------------------------------
meta = undefined       => status = skip
meta_ver = undefined   => status = skip
#files = 0             => status = skip
#mismatched = 0        => status = pass /\ score = 100
score >= 90            => status = pass
score >= 50            => status = warn
score < 50             => status = fail

SIDE EFFECTS

Reads each .pm file once; no network I/O.

USAGE EXAMPLE

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