File Coverage

=head1 VERSION

Version 0.41

=head1 DESCRIPTION

Analyses the return metadata of a schema's output section and produces
stability and consistency scores along with a list of risk flags. This
is used by L<App::Test::Generator> to assess how reliably a function's
return value can be tested.

=head2 new

Construct a new ReturnMeta analyser.

    my $analyser = App::Test::Generator::Analyzer::ReturnMeta->new;

=head3 Arguments

None.

=head3 Returns

A blessed hashref.

=head3 API specification

=head4 input

    {}

=head4 output

    {
        type => OBJECT,
        isa  => 'App::Test::Generator::Analyzer::ReturnMeta',
    }

=cut

=head2 analyze

Analyse the C<output> section of a schema hashref and return a scoring
report covering stability, consistency, and risk flags.

    my $analyser = App::Test::Generator::Analyzer::ReturnMeta->new;
    my $report   = $analyser->analyze($schema);

    printf "Stability:   %d\n", $report->{stability_score};
    printf "Consistency: %d\n", $report->{consistency_score};
    printf "Risks:       %s\n", join(', ', @{ $report->{risk_flags} });

=head3 Arguments

=over 4

=item * C<$schema>

A hashref that may include an C<output> key containing return metadata.
The C<output> hashref may include any of the following keys:

=over 4

=item C<_context_aware> — true if the function returns differently in
list vs scalar context.

=item C<_returns_self> — true if the function returns C<$self>.

=item C<type> — the declared return type string e.g. C<object>,
C<boolean>, C<string>.

=item C<_error_handling> — a hashref with boolean keys C<implicit_undef>,
C<empty_list>, and C<exception_handling>.

=item C<_error_return> — the value returned on error e.g. C<undef>.

=back

=back

=head3 Returns

A hashref with three keys:

=over 4

=item * C<stability_score> — integer in [0, 100]. Higher is more stable.

=item * C<consistency_score> — integer in [0, 100]. Higher is more
consistent.

=item * C<risk_flags> — arrayref of string risk identifiers detected
during analysis.

=back

=head3 Notes

Both scores start at 100 and are reduced by penalties for each detected
risk pattern. A small bonus is applied to stability for boolean return
types, but since C<stability_score> starts at 100 and is clamped to
[0, 100] after all adjustments, this bonus is a no-op unless an earlier
penalty has already reduced the score below 100 — for a boolean-returning
function with no other detected risk, C<stability_score> is unaffected
by C<$BONUS_BOOLEAN_STABILITY> and remains 100.

=head3 API specification

=head4 input

    {
        self   => { type => OBJECT, isa => 'App::Test::Generator::Analyzer::ReturnMeta' },
        schema => { type => HASHREF },
    }

=head4 output

    {
        type    => HASHREF,
        keys    => {
            stability_score   => { type => SCALAR },
            consistency_score => { type => SCALAR },
            risk_flags        => { type => ARRAYREF },
        },
    }

=cut