package App::Test::Generator::Analyzer::Return;

use strict;
use warnings;
use Carp         qw(croak);
use Readonly;
use Scalar::Util qw(blessed);

# --------------------------------------------------
# Evidence weights for each detected return pattern.
# Higher weights indicate stronger signals that the
# detected pattern is the primary return behaviour.
# --------------------------------------------------
Readonly my $WEIGHT_RETURNS_PROPERTY => 20;
Readonly my $WEIGHT_RETURNS_SELF     => 15;
Readonly my $WEIGHT_RETURNS_CONSTANT => 10;

our $VERSION = '0.46';

=head1 VERSION

Version 0.46

=head1 DESCRIPTION

Analyses the source code of a method and adds evidence to a
L<App::Test::Generator::Model::Method> object describing what kind of
value the method returns. Evidence is used downstream by
L<App::Test::Generator::Model::Method/resolve_return_type> to determine
the most likely return type.

=head2 new

Construct a new Return analyser.

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

=head3 Arguments

None.

=head3 Returns

A blessed hashref.

=head3 API specification

=head4 input

    {}

=head4 output

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

=cut

sub new {
	my $class = $_[0];
	return bless {}, $class;
}

=head2 analyze

Scan the source code of a method for return patterns and add weighted
evidence to the method object. Detects three patterns: returning a
property from C<$self>, returning C<$self> itself, and returning a
constant literal value.

    my $analyser = App::Test::Generator::Analyzer::Return->new;
    $analyser->analyze($method);

    my $type = $method->resolve_return_type;

=head3 Arguments

=over 4

=item * C<$method>

Normally an L<App::Test::Generator::Model::Method> object; evidence is
added to it in place via C<add_evidence>. A plain hashref with a
C<source> or C<body> key is also accepted defensively (as SchemaExtractor
callers may pass one), but in that case no evidence is recorded — only
a Model::Method object exposing both C<source()> and C<add_evidence()>
actually accumulates evidence.

=back

=head3 Returns

Nothing (undef). All results are communicated via side effects on the
C<$method> object.

=head3 Notes

The interface of this analyser differs from
L<App::Test::Generator::Analyzer::ReturnMeta>, which operates on a raw
schema hashref. This analyser operates on a C<Model::Method> object
directly.

=head3 API specification

=head4 input

    {
        self   => { type => OBJECT, isa => 'App::Test::Generator::Analyzer::Return' },
        method => { type => OBJECT, isa => 'App::Test::Generator::Model::Method' },
    }

=head4 output

    { type => UNDEF }

=cut

sub analyze {
	my ($self, $method) = @_;

	# Accept either a Model::Method object or a raw hashref,
	# since callers in SchemaExtractor pass raw hashrefs
	my $source = blessed($method) && $method->can('source')
		? $method->source()
		: ($method->{source} // $method->{body} // '');

	my $add = blessed($method) && $method->can('add_evidence')
		? sub { $method->add_evidence(@_) }
		: sub {};

	# --------------------------------------------------
	# Detect: return $self->{property}
	# Negative lookahead ensures this does not also match
	# plain return $self (handled separately below).
	# Matched with /g so a method with several differing
	# property-returning branches contributes evidence for
	# each one found, not just the first in the source.
	# --------------------------------------------------
	while($source =~ /return\s+\$self->\{(\w+)\}/g) {
		$add->(
			category => 'return',
			signal   => 'returns_property',
			value    => $1,
			weight   => $WEIGHT_RETURNS_PROPERTY,
		);
	}

	# --------------------------------------------------
	# Detect: return $self
	# \b after \$self prevents matching variable names that
	# merely start with "self" (e.g. $self_backup, $selfish);
	# the negative lookahead then excludes return $self->{...}
	# which is a property return handled above. Matched with
	# /g for the same multi-occurrence reason as above.
	# --------------------------------------------------
	while($source =~ /return\s+\$self\b(?!->)/g) {
		$add->(
			category => 'return',
			signal   => 'returns_self',
			weight   => $WEIGHT_RETURNS_SELF,
		);
	}

	# --------------------------------------------------
	# Detect: return of a constant literal — quoted string,
	# numeric literal, or undef. All indicate the method
	# returns a fixed value rather than a computed state.
	# Matched with /g for the same multi-occurrence reason
	# as the patterns above.
	# --------------------------------------------------
	while($source =~ /return\s+(?:['"\d]|undef\b)/g) {
		$add->(
			category => 'return',
			signal   => 'returns_constant',
			weight   => $WEIGHT_RETURNS_CONSTANT,
		);
	}

	return;
}

=head1 LICENCE AND COPYRIGHT

Copyright 2025-2026 Nigel Horne.

Usage is subject to GPL2 licence terms.
If you use it,
please let me know.

=cut

1;
