view release on metacpan or  search on metacpan

lib/App/Test/Generator/Analyzer/Return.pm  view on Meta::CPAN

=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;