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

NAME

Test::CPAN::Health::Check::MetaJSON - Check that META.json is present, valid, and complete

SYNOPSIS

use Test::CPAN::Health::Check::MetaJSON;

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

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

DESCRIPTION

Verifies that the distribution ships a well-formed META.json (preferred) or META.yml (fallback) and that the required CPAN::Meta v2 fields -- name, version, abstract, author, license -- are present and non-empty.

Distribution->meta searches in order: META.json, META.yml, MYMETA.json, MYMETA.yml. MYMETA files are generated by perl Makefile.PL and serve as a fallback for local checkouts. Canonical META files are produced by make distdir (MakeMaker) or dzil build (Dist::Zilla) and must be committed to the repository separately.

Score matrix:

  • 100 -- META.json present; all required fields populated.

  • 70 -- Only META.yml present; all required fields populated.

  • 50 -- Only MYMETA.json or MYMETA.yml present; all required fields populated.

  • 40 -- META.json present; one or more required fields missing/vague.

  • 25 -- Only META.yml present; one or more required fields missing/vague.

  • 15 -- Only MYMETA present; one or more required fields missing/vague.

  • 0 -- No META or MYMETA file found.

LIMITATIONS

  • The check reads whichever META file Distribution->meta resolves. It does not independently re-parse the file.

  • abstract is considered missing when it is the literal string 'unknown', which Dist::Zilla and MakeMaker sometimes use as a placeholder.

run

PURPOSE

Determine whether a META.json (or META.yml) exists and contains the minimum required metadata fields.

API SPECIFICATION

INPUT

dist     Test::CPAN::Health::Distribution  required
context  Hashref                           optional  prior check results

OUTPUT

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

MESSAGES

Code  | Severity | Message                                   | Resolution
------+----------+-------------------------------------------+-----------
MJ001 | FAIL     | No META.json or META.yml found            | Generate META files
MJ002 | WARN     | META missing required fields: {list}      | Add missing fields
MJ003 | WARN     | META.yml present but META.json is missing | Generate META.json
MJ004 | PASS     | META.json is present and complete         |

FORMAL SPECIFICATION

-- Z schema (placeholder) --
MetaJSONOp
dist     : Distribution
has_json : Boolean
meta     : CPAN::Meta | undefined
missing  : seq String
-------------------------------------------------------
meta = undefined => status = fail /\ score = 0
#missing > 0 /\ has_json  => status = warn /\ score = 50
#missing > 0 /\ ~has_json => status = warn /\ score = 30
#missing = 0 /\ ~has_json => status = warn /\ score = 70
#missing = 0 /\ has_json  => status = pass /\ score = 100

SIDE EFFECTS

None. Uses the already-parsed META object from $dist-meta>.

USAGE EXAMPLE

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