| 1 | package App::Test::Generator::Mutant; | ||||||||||
| 2 | |||||||||||
| 3 | 47 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | 47 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 5 | 47 | ▶ | use Carp qw(croak); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 6 | |||||||||||
| 7 | 47 | our $VERSION = '0.49'; | |||||||||
| 8 | |||||||||||
| 9 | =head1 VERSION | ||||||||||
| 10 | |||||||||||
| 11 | Version 0.49 | ||||||||||
| 12 | |||||||||||
| 13 | =head1 DESCRIPTION | ||||||||||
| 14 | |||||||||||
| 15 | Represents a single mutant - a specific transformation of a source file | ||||||||||
| 16 | that a test suite should be able to detect. Each mutant carries the | ||||||||||
| 17 | metadata needed to identify it, locate it in the source, and apply the | ||||||||||
| 18 | transformation to a fresh L<PPI::Document> copy at test time. | ||||||||||
| 19 | |||||||||||
| 20 | =head2 new | ||||||||||
| 21 | |||||||||||
| 22 | Construct a new mutant object. | ||||||||||
| 23 | |||||||||||
| 24 | my $mutant = App::Test::Generator::Mutant->new( | ||||||||||
| 25 | id => 'NUM_BOUNDARY_10_5_!=', | ||||||||||
| 26 | description => 'Numeric boundary flip == to !=', | ||||||||||
| 27 | original => '==', | ||||||||||
| 28 | line => 10, | ||||||||||
| 29 | type => 'comparison', | ||||||||||
| 30 | group => 'NUM_BOUNDARY:10', | ||||||||||
| 31 | transform => sub { | ||||||||||
| 32 | my ($doc) = @_; | ||||||||||
| 33 | # ... modify $doc in place ... | ||||||||||
| 34 | }, | ||||||||||
| 35 | ); | ||||||||||
| 36 | |||||||||||
| 37 | =head3 Arguments | ||||||||||
| 38 | |||||||||||
| 39 | =over 4 | ||||||||||
| 40 | |||||||||||
| 41 | =item * C<id> | ||||||||||
| 42 | |||||||||||
| 43 | A unique string identifying this mutant. Required. | ||||||||||
| 44 | |||||||||||
| 45 | =item * C<description> | ||||||||||
| 46 | |||||||||||
| 47 | A human-readable description of the mutation. Required. | ||||||||||
| 48 | |||||||||||
| 49 | =item * C<original> | ||||||||||
| 50 | |||||||||||
| 51 | The original source token or expression being mutated. Required. | ||||||||||
| 52 | |||||||||||
| 53 | =item * C<line> | ||||||||||
| 54 | |||||||||||
| 55 | The line number in the source file where the mutation occurs. Required. | ||||||||||
| 56 | |||||||||||
| 57 | =item * C<transform> | ||||||||||
| 58 | |||||||||||
| 59 | A CODE reference that accepts a L<PPI::Document> and applies the | ||||||||||
| 60 | mutation to it in place. Required. | ||||||||||
| 61 | |||||||||||
| 62 | =item * C<type> | ||||||||||
| 63 | |||||||||||
| 64 | An optional string classifying the mutation kind e.g. C<comparison>, | ||||||||||
| 65 | C<boolean>. | ||||||||||
| 66 | |||||||||||
| 67 | =item * C<group> | ||||||||||
| 68 | |||||||||||
| 69 | An optional string grouping related mutants together e.g. all mutations | ||||||||||
| 70 | on the same source line. | ||||||||||
| 71 | |||||||||||
| 72 | =item * C<context> | ||||||||||
| 73 | |||||||||||
| 74 | An optional string classifying the syntactic context the mutation was | ||||||||||
| 75 | taken from, e.g. C<conditional> when the mutated code sits inside an | ||||||||||
| 76 | C<if>/C<unless>/C<while>/C<until> condition, or C<statement>/C<expression> | ||||||||||
| 77 | otherwise. Used by L<App::Test::Generator::Mutator>'s fast-mode dedup to | ||||||||||
| 78 | recognise mutations that Perl's own boolean coercion already makes | ||||||||||
| 79 | redundant. | ||||||||||
| 80 | |||||||||||
| 81 | =item * C<line_content> | ||||||||||
| 82 | |||||||||||
| 83 | An optional string holding the raw source text of the line the mutation | ||||||||||
| 84 | targets. Used by L<App::Test::Generator::Mutator>'s fast-mode dedup to | ||||||||||
| 85 | skip mutations on comment-only lines. | ||||||||||
| 86 | |||||||||||
| 87 | =back | ||||||||||
| 88 | |||||||||||
| 89 | =head3 Returns | ||||||||||
| 90 | |||||||||||
| 91 | A blessed hashref representing the mutant. Croaks if any required | ||||||||||
| 92 | attribute is missing or if C<transform> is not a CODE reference. | ||||||||||
| 93 | |||||||||||
| 94 | =head3 API specification | ||||||||||
| 95 | |||||||||||
| 96 | =head4 input | ||||||||||
| 97 | |||||||||||
| 98 | { | ||||||||||
| 99 | id => { type => SCALAR }, | ||||||||||
| 100 | description => { type => 'string' }, | ||||||||||
| 101 | original => { type => SCALAR }, | ||||||||||
| 102 | line => { type => SCALAR }, | ||||||||||
| 103 | transform => { type => CODEREF }, | ||||||||||
| 104 | type => { type => SCALAR, optional => 1 }, | ||||||||||
| 105 | group => { type => SCALAR, optional => 1 }, | ||||||||||
| 106 | context => { type => SCALAR, optional => 1 }, | ||||||||||
| 107 | line_content => { type => SCALAR, optional => 1 }, | ||||||||||
| 108 | } | ||||||||||
| 109 | |||||||||||
| 110 | =head4 output | ||||||||||
| 111 | |||||||||||
| 112 | { | ||||||||||
| 113 | type => 'object', | ||||||||||
| 114 | isa => 'App::Test::Generator::Mutant', | ||||||||||
| 115 | } | ||||||||||
| 116 | |||||||||||
| 117 | =cut | ||||||||||
| 118 | |||||||||||
| 119 | 5147 | ▶ | sub new { | ||||||||
|
Subroutine
new: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||
| 120 | 5147 | my ($class, %args) = @_; | |||||||||
| 121 | |||||||||||
| 122 | # Validate all required attributes are present | ||||||||||
| 123 | 5147 | for my $required (qw(id description original line transform)) { | |||||||||
| 124 | croak "Missing required attribute: $required" | ||||||||||
| 125 | 25705 | ▶ | unless exists $args{$required}; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 126 | } | ||||||||||
| 127 | |||||||||||
| 128 | # Ensure transform is actually executable | ||||||||||
| 129 | 5132 | ▶ | croak 'transform must be a CODE reference' unless ref($args{transform}) eq 'CODE'; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 130 | |||||||||||
| 131 | 5123 | return bless \%args, $class; | |||||||||
| 132 | } | ||||||||||
| 133 | |||||||||||
| 134 | =head2 id | ||||||||||
| 135 | |||||||||||
| 136 | Return the unique identifier for this mutant. | ||||||||||
| 137 | |||||||||||
| 138 | my $id = $mutant->id; | ||||||||||
| 139 | |||||||||||
| 140 | =head3 API specification | ||||||||||
| 141 | |||||||||||
| 142 | =head4 input | ||||||||||
| 143 | |||||||||||
| 144 | { self => { type => 'object', isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 145 | |||||||||||
| 146 | =head4 output | ||||||||||
| 147 | |||||||||||
| 148 | { type => SCALAR } | ||||||||||
| 149 | |||||||||||
| 150 | =cut | ||||||||||
| 151 | |||||||||||
| 152 | 160 | ▶ | sub id { | ||||||||
|
Subroutine
id: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 153 | 160 | return $_[0]->{id}; | |||||||||
| 154 | } | ||||||||||
| 155 | |||||||||||
| 156 | =head2 description | ||||||||||
| 157 | |||||||||||
| 158 | Return the human-readable description of the mutation. | ||||||||||
| 159 | |||||||||||
| 160 | my $desc = $mutant->description; | ||||||||||
| 161 | |||||||||||
| 162 | =head3 API specification | ||||||||||
| 163 | |||||||||||
| 164 | =head4 input | ||||||||||
| 165 | |||||||||||
| 166 | { self => { type => 'object', isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 167 | |||||||||||
| 168 | =head4 output | ||||||||||
| 169 | |||||||||||
| 170 | { type => SCALAR } | ||||||||||
| 171 | |||||||||||
| 172 | =cut | ||||||||||
| 173 | |||||||||||
| 174 | 258 | ▶ | sub description { $_[0]->{description} } | ||||||||
|
Subroutine
description: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 175 | |||||||||||
| 176 | =head2 original | ||||||||||
| 177 | |||||||||||
| 178 | Return the original source token or expression that is being mutated. | ||||||||||
| 179 | |||||||||||
| 180 | my $orig = $mutant->original; | ||||||||||
| 181 | |||||||||||
| 182 | =head3 API specification | ||||||||||
| 183 | |||||||||||
| 184 | =head4 input | ||||||||||
| 185 | |||||||||||
| 186 | { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 187 | |||||||||||
| 188 | =head4 output | ||||||||||
| 189 | |||||||||||
| 190 | { type => SCALAR } | ||||||||||
| 191 | |||||||||||
| 192 | =cut | ||||||||||
| 193 | |||||||||||
| 194 | 432 | ▶ | sub original { $_[0]->{original} } | ||||||||
|
Subroutine
original: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 195 | |||||||||||
| 196 | =head2 line | ||||||||||
| 197 | |||||||||||
| 198 | Return the line number in the source file where the mutation occurs. | ||||||||||
| 199 | |||||||||||
| 200 | my $line = $mutant->line; | ||||||||||
| 201 | |||||||||||
| 202 | =head3 API specification | ||||||||||
| 203 | |||||||||||
| 204 | =head4 input | ||||||||||
| 205 | |||||||||||
| 206 | { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 207 | |||||||||||
| 208 | =head4 output | ||||||||||
| 209 | |||||||||||
| 210 | { type => SCALAR } | ||||||||||
| 211 | |||||||||||
| 212 | =cut | ||||||||||
| 213 | |||||||||||
| 214 | 1074 | ▶ | sub line { $_[0]->{line} } | ||||||||
|
Subroutine
line: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 215 | |||||||||||
| 216 | =head2 transform | ||||||||||
| 217 | |||||||||||
| 218 | Return the CODE reference that applies the mutation to a | ||||||||||
| 219 | L<PPI::Document> copy. | ||||||||||
| 220 | |||||||||||
| 221 | my $xform = $mutant->transform; | ||||||||||
| 222 | $xform->($doc_copy); | ||||||||||
| 223 | |||||||||||
| 224 | =head3 API specification | ||||||||||
| 225 | |||||||||||
| 226 | =head4 input | ||||||||||
| 227 | |||||||||||
| 228 | { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 229 | |||||||||||
| 230 | =head4 output | ||||||||||
| 231 | |||||||||||
| 232 | { type => CODEREF } | ||||||||||
| 233 | |||||||||||
| 234 | =cut | ||||||||||
| 235 | |||||||||||
| 236 | 85 | ▶ | sub transform { $_[0]->{transform} } | ||||||||
|
Subroutine
transform: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 237 | |||||||||||
| 238 | =head2 type | ||||||||||
| 239 | |||||||||||
| 240 | Return the optional mutation type classification string, | ||||||||||
| 241 | e.g. C<comparison> or C<boolean>. | ||||||||||
| 242 | |||||||||||
| 243 | my $type = $mutant->type; | ||||||||||
| 244 | |||||||||||
| 245 | =head3 API specification | ||||||||||
| 246 | |||||||||||
| 247 | =head4 input | ||||||||||
| 248 | |||||||||||
| 249 | { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 250 | |||||||||||
| 251 | =head4 output | ||||||||||
| 252 | |||||||||||
| 253 | { type => SCALAR, optional => 1 } | ||||||||||
| 254 | |||||||||||
| 255 | =cut | ||||||||||
| 256 | |||||||||||
| 257 | 46 | ▶ | sub type { $_[0]->{type} } | ||||||||
|
Subroutine
type: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 258 | |||||||||||
| 259 | =head2 group | ||||||||||
| 260 | |||||||||||
| 261 | Return the optional group string that clusters related mutants, | ||||||||||
| 262 | e.g. all mutations targeting the same source line. | ||||||||||
| 263 | |||||||||||
| 264 | my $group = $mutant->group; | ||||||||||
| 265 | |||||||||||
| 266 | =head3 API specification | ||||||||||
| 267 | |||||||||||
| 268 | =head4 input | ||||||||||
| 269 | |||||||||||
| 270 | { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 271 | |||||||||||
| 272 | =head4 output | ||||||||||
| 273 | |||||||||||
| 274 | { type => SCALAR, optional => 1 } | ||||||||||
| 275 | |||||||||||
| 276 | =cut | ||||||||||
| 277 | |||||||||||
| 278 | 31 | ▶ | sub group { $_[0]->{group} } | ||||||||
|
Subroutine
group: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 279 | |||||||||||
| 280 | =head2 context | ||||||||||
| 281 | |||||||||||
| 282 | Return the optional syntactic-context classification string, | ||||||||||
| 283 | e.g. C<conditional> or C<statement>. | ||||||||||
| 284 | |||||||||||
| 285 | my $context = $mutant->context; | ||||||||||
| 286 | |||||||||||
| 287 | =head3 API specification | ||||||||||
| 288 | |||||||||||
| 289 | =head4 input | ||||||||||
| 290 | |||||||||||
| 291 | { self => { type => OBJECT, isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 292 | |||||||||||
| 293 | =head4 output | ||||||||||
| 294 | |||||||||||
| 295 | { type => SCALAR, optional => 1 } | ||||||||||
| 296 | |||||||||||
| 297 | =cut | ||||||||||
| 298 | |||||||||||
| 299 | 390 | ▶ | sub context { $_[0]->{context} } | ||||||||
|
Subroutine
context: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 300 | |||||||||||
| 301 | =head2 line_content | ||||||||||
| 302 | |||||||||||
| 303 | Return the optional raw source text of the line this mutant targets. | ||||||||||
| 304 | |||||||||||
| 305 | my $text = $mutant->line_content; | ||||||||||
| 306 | |||||||||||
| 307 | =head3 API specification | ||||||||||
| 308 | |||||||||||
| 309 | =head4 input | ||||||||||
| 310 | |||||||||||
| 311 | { self => { type => 'object', isa => 'App::Test::Generator::Mutant' } } | ||||||||||
| 312 | |||||||||||
| 313 | =head4 output | ||||||||||
| 314 | |||||||||||
| 315 | { type => 'string', optional => 1 } | ||||||||||
| 316 | |||||||||||
| 317 | =cut | ||||||||||
| 318 | |||||||||||
| 319 | 401 | ▶ | sub line_content { $_[0]->{line_content} } | ||||||||
|
Subroutine
line_content: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 320 | |||||||||||
| 321 | =head1 AUTHOR | ||||||||||
| 322 | |||||||||||
| 323 | Nigel Horne, C<< <njh at nigelhorne.com> >> | ||||||||||
| 324 | |||||||||||
| 325 | Portions of this module's initial design and documentation were created | ||||||||||
| 326 | with the assistance of AI. | ||||||||||
| 327 | |||||||||||
| 328 | =head1 LICENCE AND COPYRIGHT | ||||||||||
| 329 | |||||||||||
| 330 | Copyright 2025-2026 Nigel Horne. | ||||||||||
| 331 | |||||||||||
| 332 | Usage is subject to the terms of GPL2. | ||||||||||
| 333 | If you use it, | ||||||||||
| 334 | please let me know. | ||||||||||
| 335 | |||||||||||
| 336 | =cut | ||||||||||
| 337 | |||||||||||
| 338 | 47 | 1; | |||||||||