is_fixable

Returns 1 when this finding carries an automated fix coderef, 0 otherwise.

icon

Returns the bracketed ASCII status icon for this finding's severity.

to_hash

Serialises the finding to a plain hashref for JSON encoding. The fix coderef is omitted.

NAME

App::Project::Doctor::Finding - A single diagnostic finding produced by a check

VERSION

0.01

SYNOPSIS

use App::Project::Doctor::Finding;

my $f = App::Project::Doctor::Finding->new(
    severity   => 'error',
    message    => 'No test files found under t/',
    check_name => 'Tests',
    fix        => sub {
        my $ctx = shift;
        # scaffold a basic test file
    },
);

printf "%s %s\n", $f->icon, $f->message;
$f->fix->($ctx) if $f->is_fixable;

DESCRIPTION

A value object representing one diagnostic item emitted by an App::Project::Doctor::Check::* plugin. Each finding carries a severity level, a human-readable message, an optional file/line location, and an optional automated fix coderef.

CONSTRUCTOR

new( %args )

my $finding = App::Project::Doctor::Finding->new(
    severity   => 'error',   # required: error|warning|pass|info
    message    => 'text',    # required non-empty string
    detail     => '...',     # optional extended explanation
    fix        => sub {...}, # optional coderef ($ctx) -> 1
    check_name => 'Tests',   # optional, default 'Unknown'
    file       => 'lib/F.pm',# optional
    line       => 42,        # optional positive integer
);

Croaks on invalid severity or empty message.

API SPECIFICATION

Input

severity   : 'error' | 'warning' | 'pass' | 'info'   default 'info'
message    : non-empty String
detail     : String                                    default ''
fix        : CodeRef ($ctx) -> 1                       optional
check_name : String                                    default 'Unknown'
file       : String                                    default ''
line       : positive Integer                          optional

Output

Blessed hashref of type App::Project::Doctor::Finding.

ACCESSORS

severity, message, detail, fix, check_name, file, line -- all read-only.

METHODS

is_fixable

Returns 1 when fix is defined, 0 otherwise.

API SPECIFICATION

Input

None.

Output

Integer 1 or 0.

has_fix

Synonym for is_fixable. Both are part of the public API.

icon

Returns the severity icon string: [v] pass, [X] error, [!] warning, [i] info.

API SPECIFICATION

Input

None.

Output

String -- one of [v], [X], [!], [i].

to_hash

Returns a plain hashref suitable for JSON encoding. fix is excluded.

API SPECIFICATION

Input

None.

Output

HashRef with keys: severity, message, detail, check_name, file, line (if set).

MESSAGES

Code | Trigger                       | Resolution
-----|-------------------------------|----------------------------
F001 | message is undef or empty     | Provide a non-empty message
F002 | severity is not a valid value | Use error|warning|pass|info

FORMAL SPECIFICATION

Finding == [
  severity   : SEVERITY,
  message    : String,
  detail     : String,
  fix        : (Context -> Bool) | undefined,
  check_name : String,
  file       : String,
  line       : N | undefined
]

SEVERITY ::= error | warning | pass | info

is_fixable : Finding -> Bool
is_fixable f == (fix f /= undefined)

LIMITATIONS

The fix coderef is not serialisable and is omitted from to_hash.

Encapsulation of private helpers is enforced by convention only; a future migration to Sub::Private in enforce mode is tracked as a TODO.

AUTHOR

Nigel Horne <njh@nigelhorne.com>

LICENSE

Copyright (C) 2026 Nigel Horne. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm App::Project::Doctor

perl -MCPAN -e shell
install App::Project::Doctor