File Coverage

=head1 NAME

App::Test::Generator::CoverageGuidedFuzzer - AFL-style coverage-guided fuzzing for App::Test::Generator

=head1 VERSION

Version 0.46

=head1 SYNOPSIS

    use App::Test::Generator::CoverageGuidedFuzzer;

    my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
        schema     => $yaml_schema,
        target_sub => \&My::Module::validate,
        iterations => 200,
        seed       => 42,
    );

    my $report = $fuzzer->run();

    # Optional: trim corpus to minimum branch-covering subset before saving
    my $stats = $fuzzer->minimize_corpus();
    printf "corpus %d -> %d entries\n", $stats->{before}, $stats->{after};

    $fuzzer->save_corpus('t/corpus/validate.json');

=head1 DESCRIPTION

Implements coverage-guided fuzzing on top of App::Test::Generator's
existing schema-driven input generation. Instead of purely random
generation it:

=over 4

=item 1. Generates or mutates a structured input

=item 2. Runs the target sub under Devel::Cover to capture branch hits

=item 3. Keeps inputs that discover new branches in a corpus

=item 4. Preferentially mutates corpus entries in future iterations

=back

This is the Perl equivalent of what AFL/libFuzzer do at the byte level,
but operating on typed, schema-validated Perl data structures.

=head1 METHODS

=head2 new

Construct a new coverage-guided fuzzer.

    my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
        schema     => $yaml_schema,
        target_sub => \&My::Module::validate,
        iterations => 200,
        seed       => 42,
        instance   => $obj,   # optional pre-built object for method calls
    );

=head3 Arguments

=over 4

=item * C<schema>

A hashref representing the parsed YAML schema for the target function.
Required.

=item * C<target_sub>

A CODE reference to the function under test. Required.

=item * C<iterations>

Number of fuzzing iterations to run. Optional - defaults to 100.

=item * C<seed>

Random seed for reproducible runs. Optional - defaults to C<time()>.

=item * C<instance>

An optional pre-built object to use as the invocant when calling the
target sub as a method.

=item * C<timeout>

Seconds to allow each C<target_sub> call before it is aborted via
C<alarm()> and recorded as a bug. Optional - defaults to 5. Set to 0
to disable the timeout (e.g. for target subs that legitimately block).

=back

=head3 Returns

A blessed hashref. Croaks if C<schema> or C<target_sub> is missing.

=head3 API specification

=head4 input

    {
        schema     => { type => HASHREF },
        target_sub => { type => CODEREF },
        iterations => { type => SCALAR,  optional => 1 },
        seed       => { type => SCALAR,  optional => 1 },
        instance   => { type => OBJECT,  optional => 1 },
        timeout    => { type => SCALAR,  optional => 1 },
    }

=head4 output

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

=head3 EXAMPLE

    my $fuzzer = App::Test::Generator::CoverageGuidedFuzzer->new(
        schema     => { name => { type => 'string' } },
        target_sub => sub { length($_[0]) },
        iterations => 50,
        seed       => 1234,
    );

=head3 MESSAGES

=over 4

=item C<schema required>

C<schema> was not supplied or was falsy (e.g. C<undef> or C<0>).

=item C<target_sub required>

C<target_sub> was not supplied or was falsy.

=back

=head3 FORMAL SPECIFICATION

Pre:  C<defined schema ∧ ref(target_sub) eq 'CODE'>

Post: C<ref(result) eq 'App::Test::Generator::CoverageGuidedFuzzer'>
      âˆ§ C<result-E<gt>{seed}> passed to C<srand()>
      âˆ§ C<result-E<gt>{corpus} eq []>

=cut

=head2 run

Run the coverage-guided fuzzing loop and return a summary report.

    my $report = $fuzzer->run();
    printf "Branches covered: %d\n", $report->{branches_covered};
    printf "Bugs found:       %d\n", $report->{bugs_found};

=head3 Arguments

None beyond C<$self>.

=head3 Returns

A hashref with keys C<total_iterations>, C<interesting_inputs>,
C<corpus_size>, C<branches_covered>, C<bugs_found>, and C<bugs>.

=head3 Notes

A C<target_sub> call that dies is only recorded in C<bugs> when the
input that triggered it is valid per C<schema>. A die triggered by an
input the schema itself marks invalid (e.g. out of the declared
C<min>/C<max> range) is expected behaviour, not a bug, and is silently
discarded.

=head3 API specification

=head4 input

    {
        self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' },
    }

=head4 output

    {
        type => HASHREF,
        keys => {
            total_iterations   => { type => SCALAR  },
            interesting_inputs => { type => SCALAR  },
            corpus_size        => { type => SCALAR  },
            branches_covered   => { type => SCALAR  },
            bugs_found         => { type => SCALAR  },
            bugs               => { type => ARRAYREF },
        },
    }

=head3 EXAMPLE

    my $report = $fuzzer->run();
    printf "Iterations:  %d\n", $report->{total_iterations};
    printf "Corpus size: %d\n", $report->{corpus_size};
    printf "Bugs found:  %d\n", $report->{bugs_found};
    for my $bug (@{ $report->{bugs} }) {
        printf "  input=%s  error=%s\n", $bug->{input}, $bug->{error};
    }

=head3 FORMAL SPECIFICATION

Pre:  C<self-E<gt>{schema}> and C<self-E<gt>{target_sub}> are set

Post: C<result-E<gt>{total_iterations} == self-E<gt>{iterations}>
      âˆ§ C<result-E<gt>{corpus_size} == scalar @{self-E<gt>{corpus}}>
      âˆ§ C<result-E<gt>{bugs_found} == scalar @{self-E<gt>{bugs}}>

=head3 PSEUDOCODE

    seed corpus with SEED_CORPUS_SIZE random inputs
    for i in 1..iterations:
        if corpus non-empty and rand < CORPUS_MUTATE_RATIO:
            input = mutate(random corpus entry)
        else:
            input = generate_random()
        run target_sub(input), record coverage and bugs
    return report hashref

=cut

=head2 corpus

Return the accumulated corpus as an arrayref of hashrefs with keys
C<input> and C<coverage>.

    my $corpus = $fuzzer->corpus();

=head3 API specification

=head4 input

    { self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' } }

=head4 output

    { type => ARRAYREF }

=head3 EXAMPLE

    my $corpus = $fuzzer->corpus();
    printf "%d entries in corpus\n", scalar @{$corpus};
    # Each entry: { input => ..., coverage => { 'file:line:branch' => 1, ... } }

=cut

=head2 bugs

Return bugs found as an arrayref of hashrefs with keys C<input> and
C<error>.

    my $bugs = $fuzzer->bugs();

=head3 API specification

=head4 input

    { self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' } }

=head4 output

    { type => ARRAYREF }

=head3 EXAMPLE

    my $bugs = $fuzzer->bugs();
    for my $b (@{$bugs}) {
        printf "Bug: input=%s  error=%s\n", $b->{input}, $b->{error};
    }

=cut

=head2 save_corpus

Serialise the corpus to a JSON file for replay or extension on future
runs.

    $fuzzer->save_corpus('t/corpus/validate.json');

=head3 Arguments

=over 4

=item * C<$path>

Path to write the JSON corpus file. Required.

=back

=head3 Returns

Nothing. Croaks if the file cannot be written or no JSON module is
available.

=head3 Side effects

Writes a JSON file to C<$path>.

=head3 API specification

=head4 input

    {
        self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' },
        path => { type => SCALAR },
    }

=head4 output

    { type => UNDEF }

=head3 EXAMPLE

    $fuzzer->run();
    $fuzzer->minimize_corpus();
    $fuzzer->save_corpus('t/corpus/my_func.json');

=head3 MESSAGES

=over 4

=item C<path required>

No path argument was supplied.

=item C<Cannot write corpus to $path: $!>

The file could not be opened for writing (permissions, missing directory, etc.).

=item C<No JSON module available; install JSON or JSON::MaybeXS>

Neither C<JSON::MaybeXS> nor C<JSON> is installed.

=back

=cut

=head2 load_corpus

Load a previously saved corpus JSON file, pre-seeding the fuzzer so
it continues from where it left off.

    $fuzzer->load_corpus('t/corpus/validate.json');

=head3 Arguments

=over 4

=item * C<$path>

Path to the JSON corpus file to load. Required.

=back

=head3 Returns

Nothing. Croaks if the file cannot be read or no JSON module is
available.

=head3 Side effects

Appends loaded entries to C<< $self->{corpus} >>.

=head3 API specification

=head4 input

    {
        self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' },
        path => { type => SCALAR },
    }

=head4 output

    { type => UNDEF }

=head3 EXAMPLE

    my $fuzzer2 = App::Test::Generator::CoverageGuidedFuzzer->new(
        schema     => $schema,
        target_sub => \&My::Module::validate,
    );
    $fuzzer2->load_corpus('t/corpus/my_func.json');
    my $report = $fuzzer2->run();

=head3 MESSAGES

=over 4

=item C<path required>

No path argument was supplied.

=item C<Cannot read corpus from $path: $!>

The file could not be opened for reading (missing file, permissions, etc.).

=back

=head3 FORMAL SPECIFICATION

Note: C<load_corpus> does B<not> restore C<bugs> from the JSON file —
the C<bugs> array in the JSON is written by C<save_corpus> but ignored on load.
The loaded fuzzer starts with an empty C<bugs> list.  Seed values are also not
restored; the constructor-supplied seed is retained.

=cut

=head2 minimize_corpus

Reduce the corpus to the smallest subset that still covers every
branch hit by the full corpus, using a greedy set-cover algorithm.

Entries without branch data (loaded from a previous run, or kept by
random sampling when Devel::Cover is unavailable) are deduplicated by
input fingerprint and retained in full — they cannot be evaluated for
coverage contribution without re-running them.  Bug-triggering inputs
are always kept regardless of coverage contribution.

    my $stats = $fuzzer->minimize_corpus();
    printf "Corpus: %d -> %d entries (%d branches covered)\n",
        $stats->{before}, $stats->{after}, $stats->{branches};

=head3 Returns

A hashref with keys C<before> (corpus size before), C<after> (corpus
size after), and C<branches> (total unique branches still covered).

=head3 API specification

=head4 input

    { self => { type => OBJECT, isa => 'App::Test::Generator::CoverageGuidedFuzzer' } }

=head4 output

    {
        type       => HASHREF,
        constraint => sub { defined $_[0]{before} && defined $_[0]{after} && defined $_[0]{branches} },
    }

=head3 EXAMPLE

    $fuzzer->run();
    my $stats = $fuzzer->minimize_corpus();
    printf "Corpus: %d -> %d entries (%d branches)\n",
        $stats->{before}, $stats->{after}, $stats->{branches};
    $fuzzer->save_corpus('t/corpus/my_func.json');

=head3 FORMAL SPECIFICATION

Post: C<result-E<gt>{before}> == pre corpus size
      âˆ§ C<result-E<gt>{after}> ≤ C<result-E<gt>{before}>
      âˆ§ C<scalar @{self-E<gt>{corpus}}> == C<result-E<gt>{after}>
      âˆ§ every branch covered by the original corpus is still covered
        by the minimized corpus
      âˆ§ every bug-triggering input survives minimization

=head3 PSEUDOCODE

    partition corpus into with-coverage and without-coverage entries
    greedy set-cover: repeatedly pick entry covering most uncovered branches
    deduplicate without-coverage entries by JSON fingerprint
    unconditionally add all bug inputs not already in minimized set
    replace self.corpus with minimized list
    return { before, after, branches }

=cut