File Coverage

=head1 PACKAGE DATA

=head2 %ACTION_UPDATES

Canonical mapping of outdated action strings to their current replacements.

    'old/action@vN' => 'old/action@vM'

This hash is the B<single source of truth> for action version knowledge.
Both C<find_outdated_actions> (detection) and C<update_actions> (mutation)
consume it so that detecting an outdated action always implies the ability
to fix it — and vice versa.

Premise 1: the Analyzer reports every key in this hash as "outdated".
Premise 2: the Fixer replaces every key with its value.
Conclusion: no detected issue is unfixable, and no fix targets an undetected issue.

=cut

=head1 NAME

App::GHGen::Fixer - Auto-fix workflow issues

=head1 SYNOPSIS

    use App::GHGen::Fixer qw(apply_fixes);

    my $fixed = apply_fixes($workflow, \@issues);

=head1 FUNCTIONS

=head2 can_auto_fix($issue)

Determine whether a given issue can be automatically resolved.

=head3 Purpose

Act as a capability gate before calling C<apply_fixes>.  Returns true only
for the four issue types that the Fixer knows how to handle.

=head3 Arguments

=over 4

=item C<$issue> (HashRef, required)

An issue hash with at least a C<type> key.  Recognised types are
C<performance>, C<security>, C<cost>, and C<maintenance>.

=back

=head3 Returns

C<1> (true) when the issue type is auto-fixable; C<0> (false) otherwise.

=head3 Side Effects

None.  Pure predicate.

=head3 Usage Example

    if (can_auto_fix($issue)) {
        apply_fixes($workflow, [$issue]);
    }

=head3 API SPECIFICATION

=head4 Input

    { issue => { type => 'hashref', required => 1 } }

=head4 Output

    { type => 'scalar' }   # boolean: 1 or 0

=head3 FORMAL SPECIFICATION

    can_auto_fix : Issue → 𝔹

    FixableTypes ≔ { performance, security, cost, maintenance }

    can_auto_fix(i) ≡ i.type ∈ FixableTypes

=cut

=head2 apply_fixes($workflow, $issues)

Apply all auto-fixable changes from C<$issues> directly to C<$workflow>.

=head3 Purpose

Iterate over C<$issues>, skip issues that are not auto-fixable, and call
the appropriate internal fix routine for each fixable type/message
combination.  Modifies C<$workflow> in place.

=head3 Arguments

=over 4

=item C<$workflow> (HashRef, required)

The parsed workflow hash to be mutated.

=item C<$issues> (ArrayRef[HashRef], required)

The issues to process.  Each must have C<type> and C<message> keys.

=back

=head3 Returns

The number of individual fix operations applied (an integer ≥ 0).

=head3 Side Effects

Modifies C<$workflow> in place.

=head3 Usage Example

    my $n = apply_fixes($workflow, \@issues);
    say "$n fix(es) applied.";

=head3 API SPECIFICATION

=head4 Input

    {
        workflow => { type => 'hashref',  required => 1 },
        issues   => { type => 'arrayref', required => 1 },
    }

=head4 Output

    { type => 'scalar' }   # non-negative integer

=head3 FORMAL SPECIFICATION

    apply_fixes : Workflow × seq Issue → â„•

    applied ≔ ∑ { fix(w, i) ∣ i ∈ issues, can_auto_fix(i) }
    result  â‰” applied

    Mutates w by applying each fix in sequence.

=cut

=head2 fix_workflow($file, $issues)

Load a workflow YAML file, apply fixes, and write it back to disk.

=head3 Purpose

Persist the results of C<apply_fixes> by reading the workflow from C<$file>
with C<YAML::XS::LoadFile>, calling C<apply_fixes>, and rewriting the file
with C<YAML::XS::DumpFile> when at least one fix was applied.

=head3 Arguments

=over 4

=item C<$file> (Str, required)

Path to a YAML workflow file.  Passed directly to C<YAML::XS::LoadFile>.

=item C<$issues> (ArrayRef[HashRef], required)

Issues to fix, each with C<type> and C<message> keys.

=back

=head3 Returns

The number of fixes applied (an integer ≥ 0).  The file is only rewritten
when the count is greater than zero.

=head3 Side Effects

Reads C<$file> from disk; rewrites C<$file> in place when fixes are applied.

=head3 Usage Example

    my $n = fix_workflow('.github/workflows/ci.yml', \@issues);
    say "$n fix(es) written to ci.yml.";

=head3 API SPECIFICATION

=head4 Input

    {
        file   => { type => 'scalar',  required => 1 },
        issues => { type => 'arrayref', required => 1 },
    }

=head4 Output

    { type => 'scalar' }   # non-negative integer

=head3 FORMAL SPECIFICATION

    fix_workflow : Path × seq Issue → â„•

    w       â‰” LoadFile(file)
    fixes   â‰” apply_fixes(w, issues)
    fixes > 0 → DumpFile(file, w)

    result ≔ fixes

=cut

=head1 AUTHOR

Nigel Horne E<lt>njh@nigelhorne.comE<gt>

L<https://github.com/nigelhorne>

=head1 COPYRIGHT AND LICENSE

Copyright 2025-2026 Nigel Horne.

Usage is subject to license terms.

The license terms of this software are as follows:

=cut